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Introduction 


tMj/elcome to OS/2 Warp Programming For Dummies, your faster-than- 
WW light-speed introduction to programming for OS/2 Warp. While this 
and other ...ForDummies books have humor as a hallmark, I promise to spare 
you interminable Star Trek puns, if for no other reason than fear of Para¬ 
mount Pictures’ considerable staff of lawyers. Well, maybe I’ll subtly slip in a 
few here and there—but I’m a writer, not a comedian, dammit! 

The stack of books that is the IBM OS/2 technical library comes up to my 
knees and, if used properly, could be better than a Soloflex for getting into 
shape. (I recommend doing deep knee lunges with Volumes 1 and 2 of the 
Presentation Manager Programming Reference .) 


The 5th Wave 


Rich Tennant 
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But you wouldn’t actually want to read these books if you wanted to get any 
programming done. 1 know, because I have read them. Well, most of them. 

But who really wants to know how to interface Warp with their old 8-track 
tapes? 

You won’t have to read them—if you buy this book now. 1 mean, right now. 
Stop browsing and go pay for it. You can come back to the aisle and continue 
reading after that. (I’ll wait.) 


About This Book 

This book is about results. About getting them. Through programming. Under 
Warp OS/2. (The marketing folks tell me this kind of short sentence style is 
exciting. I think they need to get out more.) 

Programming follows several 90% rules. One of those rules is “The first 90% 
of the project takes 90% of the time, and the last 10% takes the other 90% of 
the time,” but that’s not really relevant here. The 90% rule that this book con¬ 
cerns itself with is this: 90% of most Warp programming questions arise in 
certain areas. Those are the areas that this book concentrates on. 

This book will not teach you how to program. There are several other good 
...For Dummies books that can teach you that, such as CFor Dummies by Dan 
Gookin. On the bright side, you don’t need to be much of a programmer. 
(Heck, my degree is in Music—don’t tell the nerds!) Programs today are com¬ 
posed basically of lots of calls to large complicated subroutines. 

This book will not make an OS/2 god out of you, although if you take your 
programs to some poor tribe of savages still using DOS, you may be able to 
get them to erect a shrine in your name. 

What you will gain from these pages is familiarity, understanding, and—if you 
really follow along and try out the examples—a certain degree of comfort. 
You should walk away from this book feeling good about yourself (not bad 
for $19.99 retail) and secure in your ability to write Warp programs. 

What you don’t know, you’ll be able to find out—either through the IBM tech¬ 
nical library, a more advanced book on OS/2 programming, on-line help, or a 
friendly OS/2 guru (there are many). You will have graduated from Dummy 
status—at least in this area. Hey, we’re all Dummies about some things! 
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What Is Warp) 

Warp is version 3.0 of IBM’s hot, hot operating system, OS/2. How hot is it? 
IBM announced that they had shipped over 1 million copies of Warp within 
about two months of its release. Two major computer clone manufacturers 
(Vobis in Germany and Osborne in Australia) started shipping Warp instead 
of Microsoft Windows with their computers in January of 1995. 

Why is it so good? The OS/2 operating system provides a number of features 
not found in most other desktop systems: a sophisticated, easy-to-use, 
object-oriented graphical user interface, preemptive multitasking, 32-bit fea¬ 
tures, a fast file system, and excellent DOS and Windows emulation. (Don’t 
worry if you don’t know what all this stuff means, you’ll find out first-hand 
later on in the book!) 

The amazing thing about Warp is that it does all this in four megabytes (MB) 
of RAM. (Earlier versions of OS/2 worked in 4MB of RAM, too, just not very 
well.) With eight megabytes of RAM—which is what Microsoft now recom¬ 
mends for their pretender to the 32-bit throne, Windows 95—you gain all the 
benefits of OS/2 without giving up much of anything. 

In this book, you’ll learn how to take advantage of OS/2’s power, including 
enhancements to earlier versions of OS/2 introduced by Warp. Soon, you 
might even be on your way toward carving a niche for yourself in a lucrative 
OS/2 software market. 


Who Are you) 

You have a basic understanding of programming. You own (or can legally get 
hold of) a compiler with which to try what you learn. 


The Languages j bu Know 

Although the complexity of the C language might seem to run counter to the 
intentions of any book “for dummies,” the plain truth of the matter is that you 
are far and away most likely to be able to get hold of a C compiler cheaply. 
Therefore, the listings in this book are in C. It’s not very idiomatic C, mind 
you. In general, my C code is as clear as can be, and my editors tell me they 
have made it more so! You won’t see me using C conventions like “var++” or 
“var+=10.” I assume that C readers can read the longer “var = var + 1” and 
“var = var + 10,” respectively, and those are more universally understood 
ways to express incrementing a variable. There is also an offer in the back of 
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this book for a disk that contains the listings from the book not only in C, but 
also in selected other languages (such as PL/I, Pascal, Prolog, and Modula-2). 
So, if you really hate C or can’t read it at all, you can just follow along with 
the code on the disk. 

The examples in this book were compiled and tested under Borland’s C++ for 
OS/2, Watcom’s C/C++ 10.0, and IBM’s C/Set++. 

This is true for all of the examples but those in Part V, “Workplace Shell 
Basics,” which were coded in IBM C/Set++ because that is the only compiler 
product of the three that currently supports the latest developments in 
Workplace Shell programming. 


About Compiling OS/2 Programs 

Because OS/2 applications tend to involve many files and C has no built-in 
way to handle these files, some compilers and environments require you to 
build make files to efficiently compile programs. Also, some compilers and 
linkers expect you to set switches to create various kinds of OS/2 applica¬ 
tions (text-based, graphical, and so forth). 

The Watcom, Borland, and IBM packages mentioned, however, all include an 
Integrated Development Environment (IDE) that allows you to work with 
“projects.” IBM’s IDE is called the WorkFrame/2; the other two call theirs the 
Watcom IDE and the Borland IDE, respectively. My advice is to use one of 
these IDEs. You tell the IDE what kind of OS/2 application you’re making, and 
it handles the rest. The IDEs also handle all the ugly details about make files. 
(Some people have trouble understanding IBM’s WorkFrame/2 version 2.0, so 
you may want to use version 1.1, which IBM includes in the 2.0 package.) 

I’m not going to cover make file creation here—it doesn’t really pertain to OS/2 
programming—so if you decide not to take my advice about using IDEs, you’ll 
have to examine your compiler documentation to learn which switches do 
what and how to build make files. (Don’t say I didn’t warn you!) In Chapter 2, 
“Understanding Warp Programs,” however, there are several tips on compiling 
OS/2 from the command line. 

An important point to bring up here is that all OS/2 compilers come with cer¬ 
tain files that you need to program OS/2, but compilers and operating sys¬ 
tems are not necessarily upgraded at the same time. Therefore, although you 
may have bought your compiler last week, it may contain support files only 
for earlier versions of OS/2. You will know if your files are old when you get 
to a section marked “Warp” in the book and, in trying to compile the pro¬ 
gram, you get an “unresolved external” error. 



You do not need to worry about this if you bought the IBM C++ compiler any 
time in the last six months. If you are using an older version of the IBM com¬ 
piler or a compiler from another vendor, you can resolve your problems by 
installing a copy of the IBM Developer’s Toolkit for OS/2 Warp and using the 
files it contains instead of the ones supplied with your compiler. 


HoW to Use This Book 

While some of my dearest friends consider me a heathen, I confess to one 
deeply held belief: Books should be written so that people can understand 
them. OS/2 Warp Programming For Dummies is a tutorial first and a reference 
second. If you read it carefully from front to back, I give you my word that 
you can understand it all. 

The first time I use a concept or a technical word I promise to explain it in 
clear English—as clear as English can be, anyway—and if I re-use that con¬ 
cept or word later, I will refer to the section in which it was introduced. This 
book contains a glossary, too, but don’t expect that to take the place of the 
standard English and computer dictionaries that I know you’re going to keep 
with you at all times. On trains. On buses. At weddings and funerals. In the 
bathroom. Everywhere. 

In exchange for you having your dictionaries handy, I promise not to use 
words that make you go rushing through them a lot. I have completely aban¬ 
doned my customary conversational style, which doth mimic the great works 
of Shakespeare. 

With this understanding, we should get along fine. Any confusions you have 
come either from a misunderstanding of an earlier point in the text or, possi¬ 
bly, from a mistake I have made. (Although I’ve never witnessed one, my 
friends assure me I make them not infrequently.) 

Ultimately, you can use this book as a reference, especially after you’ve read 
it once and understood it. If you have some other experience with OS/2 pro¬ 
gramming, perhaps even just graphical user interface (GUI) programming in 
general, you might be able to get away with skipping around. Even if you 
don’t have much experience, I’ve done my best to make the parts of the book 
as self-contained as possible. So if a particular part doesn’t interest you, you 
can skip ahead and come back later if necessary. 

But I guarantee your success if you read this book from cover to cover. (Uh, 
that’s not a legal guarantee, mind you, just my earnest, sincere, non-legally 
binding belief.) 
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A Word on Code Samples 

When writing a book on programming—particularly one that tries to cover as 
broad a subject as OS/2—authors must balance the desire to demonstrate a 
wide variety of features against the desire to show how things are done using 
code that serves a realistic purpose. (There, a peek into the mind of com¬ 
puter book authors at no extra charge!) 

For example, a lot of books write long, complete programs—a great market¬ 
ing ploy (“Build your own astrology forecaster in three days while learning 
C++!”)—that in some cases fill up page after page with listings. Or, in the case 
of at least one book, page after page of zeros and ones describing bitmaps. 

No kidding. 

At the other end of the spectrum are books that don’t do much more than 
rephrase the reference manuals. All their usage tips are abstract. 

My approach is to show you simple programs that demonstrate one or more 
features of OS/2.1 keep the code repetition to a minimum by working from a 
basic framework first introduced in Chapter 3, “The Basic Application Frame¬ 
work Explained,” and revised as you learn new and important things about 
OS/2. 


HoW This Book Is Organized 

Part I: From Square One 
(and Ground Zero!) 

Text mode programming under DOS was easy, or at least relatively easy com¬ 
pared to the complexities introduced by graphical user interfaces. Part I 
introduces the skills needed to create (non-text mode) OS/2 applications, 
explores why they are so complex, and looks at ways to simplify the process. 

Chapters 1 and 2 introduce the basic concepts and terminology required to 
understand OS/2 applications. Understanding the material in these chapters 
is a prerequisite for the rest of the book. If you have no experience with OS/2 
or GUI programming, you should read all six chapters in this part in 
sequence. 
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Part II: Resources and Dialogs—Getting 
in Touch With J four OS 

In Part II, you explore resources under OS/2, and the construction of dialogs. 
You also learn how some elements can be created without coding, and play 
around with bitmaps and pointers. 


Part III: OS/2 Controls 

In Part III, you learn about all the little features that go into making a graphi¬ 
cal application: buttons, entry fields, notebooks, and so on. 

The chapters in this part can be used for reference, and do not need to be 
read sequentially. 


Part W: Polish and Panache 

Windows and dialogs are just the start of a great OS/2 application. In Part IV 
you learn about OS/2’s Graphics Programming Interface, multithreading, and 
more. 

You also learn how to do some basic stuff with the Workplace Shell and how 
to add items programmatically to the LaunchPad. 


Part V: Workplace Shell Basics 

Here you explore the exciting and sometimes bizarre world of Workplace 
Shell (WPS) programming. Find out how to create your own WPS objects, 
how to customize pop-up menus and settings notebooks, and how to imple¬ 
ment drag-and-drop in your WPS applications. 

This part is best read sequentially, as each chapter by necessity builds on 
what comes before. 


Part VI: The Part of Tens 

The last two chapters of the book serve as a reference section and as a 
launching point for future studies. One chapter is dedicated to alternatives to 
C and C++, for those of you who feel that there are not enough options under 
OS/2. The last chapter contains ten topics you can study to increase your 
OS/2 knowledge. 
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Icons Used in This Book 


So, what’s a technical book these days without a bunch of silly pictures in the 
margin? Here are the icons you’ll see in this book, and what they mean. 




Technical stuff. Well, as the entire book is technical, this indicates stuff 
that’s more technical than the rest. Or sometimes material that is stated in a 
more formal manner. This is the stuff you’ll need to read more about in 
other books and to discuss with other people. Occasionally, this icon may 
mark a section of text that deals with a very technical and not commonly 
used area. f§ 

Important information for making your life easier. There’s a lot of this. If 


Stuff that’ll make you slap your head like Homer Simpson if you forget it. 
Often this is a recap of an important earlier point, a 


Ways to get into (or keep out of) trouble, m 



Differences between C and other languages. In some cases, a common C prac¬ 
tice might not translate to other languages, m 



Warp-specific information. That is, material that can be applied only to OS/2 
version 3.0 and later. It is important not to use this if you want to write pro¬ 
grams that run under earlier versions of OS/2. If you have problems with stuff 
that falls into this category, you know your compiler’s OS/2 support files are 
out of date, s 



Advice on making your applications more WPS-like. The more WPS-like, the 
better, right? m 



A mini-advertisement. No, I’m not getting paid to endorse products, but cer¬ 
tain tools (whatever brand) are useful, and I’ll let you know what they are 
and how they’re used. ■ 
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Just me expressing an opinion or blabbering about history. Usually there’s a 
point to my rants. That is, they usually refer to some aspect of OS/2 and 
v^w/4/ should enrich your understanding of some facet or feature. But you probably 
wouldn’t suffer too much if you skipped them. (You might hurt my feelings, 
though.) 


A Note on the Tables 

There are a number of tables in this book. It is impossible to describe Warp 
programming without them. However, you shouldn’t expect yourself to mem¬ 
orize these, or even, necessarily, to grasp the full impact of certain items 
specified in the tables. Sometimes a superficial understanding is more expe¬ 
dient than trying to work out exactly what some feature is used for—ulti¬ 
mately you will understand, if you need to. (And, conversely, there will be 
some stuff that you decide is simply goofy.) 


Contentions Used in This Book 

Here are a couple of conventions that you should be aware of: 

is The asterisk (*) is used in the text after a prefix to designate categories 
of items. So if I say “If you remember the Cat* routines...,” you should 
understand this to mean “all the routines whose names start with Cat”, 
| as in CatScratchFever or CatOnAHotTinRoof. 

I refer to your “source directory,” I mean whatever directory you keep 
the code samples in. 

On llour Mark... 

Before starting to read, start up Warp. You probably could learn a great deal 
from this book without turning on your computer, but you’ll learn more and 
you’ll learn it better if you’ve got Warp and your compiler at the ready. In 
fact, you’re much less likely to get confused or lost if you can test the mater¬ 
ial as you’re reading. Even if I make a simple statement about the nature of 
windows or icons in Warp, you can verify them for yourself if you’ve got 
Warp running. 


Let’s get going! 









"FORUS, ims 1UTAL INTEGRATION OR NOTHING. fCklNSWCe- 
AT THIS TERMING. AlCNE I CAN GET DEHmwm. DATA, 
PRINTER AND SICRAQE RESOURCES, ESPN, ACME SW/A/G 

metwcrk am? the rn/ie channel." 






In This Part 



S/2 is what is known as a “rich environment,” which 
means that no ordinary human can absorb all of its 


features and still have a life. The following chapters intro 


duce you to the basic concepts and give you a taste of 


how you can program to take advantage of these 


features. Many of the concepts here hold true for any 
graphically driven interface. Few are peculiar to OS/2. 


The first two chapters introduce the basic terminology 
used throughout the rest of the book. And there are sev¬ 
eral concrete, simple examples of OS/2 programs in the 
other four chapters that you won’t want to miss. (Really, 
they’re quite exciting!) 



Chapter 1 

The Elements of OS/2 


In This Chapter 

An overview of the Operating System/2 
!► The underbelly of OS/2 (the stuff you can’t see) 

/> The overbelly(?) of OS/2 (the stuff you can see) 

The Workplace Shell versus the Presentation Manager 
A description of the LaunchPad 


( he Operating System 2 (OS/2) is an old, old operating system (or “OS”). As 
a matter of fact, it was designed as the successor to DOS shortly before 
DOS really took off. And like anyone or anything with a history, 0S/2’s history 
is checkered. Worst (best?) of all, that history is clouded with politics, bad 
decisions, treachery, and deceit. Sort of a nerdy Peyton Place. 

For some who choose OS/2, the choice is simply a matter of wanting consis¬ 
tency. Bill Gates, president of Microsoft Corporation, once said that OS/2 was 
the greatest program ever written. Microsoft has since promoted Windows, 
Windows NT, “Cairo,” and now Windows 95 as the operating systems to use. 
IBM, on the other hand, has remained true to the vision of OS/2, even under 
the most harrowing circumstances. And while OS/2 floundered as a joint 
effort between Microsoft and IBM, IBM’s solo efforts have made it one of the 
most popular programs of all time. 

Fortunately we’re beyond the propaganda now, and OS/2 version 3.0 (a.k.a. 
Warp) has come into its own in a big way. With roughly 10 million OS/2 
users—and growing fast—we no longer have to care about politics or history. 
All we have to care about is figuring out how to best use the incredible vol¬ 
ume of OS/2 services (called the Application Programming Interface or API) so 
that we can write OS/2 applications (or “apps,” for short) for ourselves and 
the millions of users who want them! 
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OS/2: Mot Just Another Pretty Interface 

OS/2 is more than the flashy graphical objects you manipulate on your Desk¬ 
top. The first versions of OS/2 even sported an interface more or less like 
DOS. (In fact, some eccentrics still configure Warp to not bring up any of the 
GUI.) A simple command line interface, replete with dir and del commands, 
was all users had to work with. So why did anyone bother? 



For a thrill, when you next boot Warp you can press Alt+Fl as soon as the 
“OS/2” appears in the upper left-hand corner of your screen. This will give 
you an option to prevent the GUI from loading, and you can pretend you’re 
using OS/2 1.0. 


OS/2 has a wealth of other features important to the programmer that place it 
head and shoulders above DOS (and Windows). For example, OS/2 can run 
multiple applications at one time through a feature known as preemptive mul¬ 
titasking. 


Think of a task as the operating system’s train of thought. DOS has a one- 
track mind; Windows can do more than one thing at a time as long as none of 
those things are very demanding. OS/2 can do, and expects to do, many 
things at once. You almost feel bad when you’re running only one program 
under OS/2. 


Windows is also called a multitasking operating system because it can do 
several things at once, but its multitasking is cooperative. In other words, 
Windows requires the cooperation of the programs running under it to multi¬ 
task—all it takes is a single naughty application to tie up the machine. Win¬ 
dows has to wait for that application to release control of the computer 
before allowing some other application to run. 

OS/2’s version of multitasking is preemptive because it can take control of the 
computer regardless of what application is running. While a graphical OS/2 
program can still tie up the user interface so that the user can’t interact with 
other programs, OS/2 will continue to run any background tasks that are 
active. Programs can be written so that they won’t tie up OS/2, of course. And 
of course, Warp allows the user to terminate rude applications. (According to 
IBM engineers, the next major version of OS/2 will prohibit the interface from 
being tied up at all.) Writing polite programs that multitask well is covered in 
Chapter 21. 
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Cmsh Protection 

Multitasking is just one of the features that made early developers prefer 
OS/2 to DOS. Another important feature is the capability to provide what a 
trademark-happy IBM has trademarked as Crash Protection. Crash Protection 
simply means that the operating system should never end unexpectedly or 
under abnormal circumstances. As you undoubtedly know, an abnormal end 
to a program or operating system is colloquially referred to as crashing. 
Crashing happens all the time under DOS and Windows—and despite IBM’s 
trademark, sometimes even under OS/2. 

But all things being equal, it happens less often under OS/2 than under those 
other, lesser operating systems. The reason the others crash more often is 
that, under DOS in particular, the machine is an open book. Any program can 
have its way with any part of the hardware. You could almost say that there 
is no such thing as a badly behaved DOS program. Occasionally, programmers 
make mistakes and write programs that accidentally read and write over 
important areas of memory, or accidentally address hardware in such a way 
as to create havoc with the system. 


In OS/2, areas of memory are protected. OS/2 knows which program 
requested access to memory and also knows which areas of memory that 



Blame the device driver 


The biggest thorn in 0S/2's side—well, in the 
side of most modern operating systems, 
really, but especially 0S/2's—is the device 
driver. Device drivers are programs that 
operate your computer's devices: the screen, 
the printer, the CD-ROM drive, and so on. A 
device can often be accessed in a generic 
way that doesn't take advantage of its full 
capabilities (for example, an SVGA monitor 
can be accessed as a regular VGA monitor). 
To make the best use of a device, an applica¬ 
tion needs to know what the device can do 
and howto make it do it. 

Under DOS, every application that wanted to 
deal with a device was forced to include its 
own special code for the device. Under OS/2, 
applications access a single set of routines for 


every device. Query routines tell them the 
capabilities of the device, which the apps can 
then access (or compensate for, should a 
piece of hardware lack a certain capability). 

The problem with device drivers is that they 
must have access to sensitive areas of mem¬ 
ory. Therefore a bug in a device driver can 
make an otherwise stable OS/2 act like DOS 
on drugs. In fact, one of the reasons users get 
so emotional over this or that operating sys¬ 
tem (as in "I hate that lousy [fill in the blank]") 
is that one or more of the device drivers for 
their particular hardware configuration is 
buggy and causes their machine to crash. 
The user (somewhat) incorrectly attributes 
this failure to the OS. 
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program is authorized to use. OS/2 warns the user that an error has 
occurred, and ends the errant program. (Users are asked whether they want 
to know the details of the crash, but as these details are written in Venusian, 
human beings have yet to comprehend their meaning.) 


Making it all Work together 

Having separate programs running on the same system and preventing them 
from accidentally sharing memory creates a new set of problems that can 
make programming consultants rich. For example, what if you have tasks A 
and B running and they want to exchange information? Naturally, OS/2 has to 
have some way of allowing them to do so. The most obvious of these would 
be sharing memory, which we’ll look at in Chapter 21. 

But the situation can be more involved than simply sharing memory. For 
example, imagine a program for tracking stocks that creates a graph based 
on data being downloaded from an on-line service. The graphing program 
can’t update the graph until the program supplying the data has finished 
downloading the information. Therefore the two programs have to be able to 
signal each other. (Chapter 21 also illustrates one way of signaling.) 

OS/2 even allows a single program to do many things at once, so that the pro¬ 
gram may require signals from other tasks. For example, a program that ren¬ 
ders complex graphics might do its calculations in the background, but then 
pop up to notify the user when the picture is complete. 


Appearances Are Everything 

Of course, OS/2 wouldn’t stand much of a chance in today’s market without a 
good, solid graphical interface. Having a fast interface too doesn’t hurt, of 
course, as Warp has proven. You’ll find most of this book dedicated to help¬ 
ing you build programs that interface graphically with the user. The modern 
user doesn’t want text interface applications, and truthfully, there isn’t much 
more to writing OS/2 text-based applications than there is to writing DOS 
text-based applications. 

OS/2 has a bit of a split personality, because its original graphic services 
were designed around an archaic philosophy that was heavily text influ¬ 
enced. (You can still see this philosophy in Windows 3.x, in fact.) Instead of a 
graphical interface, they provided more of a graphical shell for a text inter¬ 
face. You still ran programs and issued commands to get around, and the 
icons on the Desktop were just shortcuts to running your programs. 
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Starting with version 2.0, OS/2 took the PC graphical user interface a step fur¬ 
ther by treating everything in the system as some kind of object. Instead of 
being concerned with the physical organization of data on the disk, the user 
had folder objects. Now instead of searching a directory tree for a file, the 
user gets to, um, search folders for files. (This actually was an improvement, 
and OS/2’s interface proved to be so much easier than Windows that 
Microsoft emulated the OS/2 GUI in Windows 95.) 

However, OS/2 has vestiges of the old GUI around—some elements of it more 
onerous than others—and this can sometimes cause confusion. 


The Presentation Manager 

Microsoft could never be accused of coming up with exciting and original 
names for things: witness “Windows 95,” the “File Manager,” the “Program 
Manager,” and now “Bob.” Likewise, IBM seems to be taxing its imagination 
when it calls all of its products “Something/2.” The close union between the 
two companies resulted in the clever naming of the OS/2 GUI as the “Presen¬ 
tation Manager.” The Presentation Manager (or PM) is a staggeringly large 
API that allows programmers to use windows, buttons, bitmaps, and other 
user interface controls relatively easily in their programs. Well, easy relative 
to trying to code all this stuff for yourself, that is! 

The point of this API is not so much to make the programmer’s life easier 
(lowering the cost of Jolt cola would have meant more) but to make the 
user’s life easier. PM ensures a consistent look and feel for OS/2 applications. 
Well, relatively consistent. Programmers are far too creative to be restrained 
by things like standards. It’s more accurate to say that PM makes the writing 
of programs that are consistent with PM’s philosophy easier. 

The advantage of the common interface is not really appreciated much any¬ 
more—it’s expected: Users can run many programs at once and layer the 
windows on the screen to their liking. They can switch from window to win¬ 
dow with impunity. Gone are the days when rude programmers could tie up 
machines forever. (Although again, creatively rude programmers can always 
find ways.) 

This book is largely concerned with teaching you the basics of the Presenta¬ 
tion Manager API in a readily consumable fashion. You’ll learn how to create 
windows, how to write text, how to put up dialogs, and so forth. And some 
books (and some operating systems!) would be content to stop there. This 
book could too, except for—the Workplace Shell! 
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The W&rkP(ace Shell 

The Workplace Shell (WPS) is one of the more modern GUIs available for any 
computer system. When you first turn on OS/2, it’s the components that 
make up the Workplace Shell that greet you: the Desktop, the icons, and what 
the icons represent (folders, data files, programs, and so on). The icons are 
called objects , and to understand how they’re different from non-object icons, 
it helps to look a bit at Windows 3.x for comparison. 

When you start Windows, it runs a program called the Program Manager. The 
Program Manager then serves as the basis for all your activities under Win¬ 
dows. Close the Program Manager and Windows will close. To work with the 
Program Manager you have to create groups and items by typing essentially, 
what you would have had to type under DOS to run the program or view the 
file. 

If you want to look at your disk drives, you have to run another program 
called the File Manager. If you see a data file in the File Manager and you want 
to look at it, you have to “associate” some program file with it. (You have to 
know which program to associate with it, too.) 

Under Windows, icons are just icons. They represent some command you 
might issue under DOS. Windows can be considered somewhat modal , in that 
the computer’s functions are separated and discrete. You enter Program 
Manager mode to run programs, you enter the File Manager to do file stuff, 
and so on. 


The OS/2 object 

As you know, OS/2 doesn’t work that way. Any object on the screen repre¬ 
sents an actual thing in your computer and can be opened, with the result 
varying according to the object: programs run; text files generally appear in 
your chosen text editor; a disk drive reveals a directory of files on the disk; 
and so forth. If you’ve used OS/2 applications much, you’ll notice that an 
OS/2 application often creates a new type of object specific to itself. 

If you’ve never noticed this, simply open up your templates folder. Templates 
look like yellow Post-It notes that you can tear off and stick somewhere. In 
fact you can tear off a new object of any type in the template by dragging it 
with the secondary mouse button. You’ll see such as standard Desktop 
objects data files, programs, folders, and printers. 

But if you have installed the Bonus Pack’s Works package, you’ll also see tem¬ 
plates called “FPWORKS DB.LDF,” “FPWORKS SS.LSS,” and “FPWORKS 
WP.LWP,” among others. These three templates represent database, spread¬ 
sheet, and word processor objects, respectively, for the Works program. You 
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may have other special templates, too—for example, a DeScribe document 
template or a VX-REXX program template, if you have purchased and 
installed those applications. 


The non-modal operating system 

As you know, you move an object in the Workplace Shell by picking it up and 
dragging it to a new location with the mouse. (This is called direct manipula¬ 
tion .) You can print an object by dragging that object to the printer icon, 
destroy it by dragging it to the shredder icon, or even import it into a running 
application by merely dropping it on the open application. 

In the Workplace Shell everything is integrated and uniform: You don’t have 
to run one program to launch applications, another to look at your disk, and 
yet another to print files. 

When a program or operating system forces you to interact with it in a cer¬ 
tain way to perform one task, and another way to perform another, it is called 
modal. You must enter different modes to do different things (File Manager 
mode to do file management, Program Manager mode to run programs, and 
so forth). 

By contrast, OS/2’s Workplace Shell allows you to act modelessly—you can 
go from file management, to printing a document, to running a program with¬ 
out a thought. This is a good thing. 

Of course, not all OS/2 programs are well integrated with WPS: If you drop 
some applications’ objects on the printer, you’ll get garbage. (You have to 
print the files from inside the applications.) But WPS integration is something 
to aspire to. 

The Workplace Shell is, in fact, a clever application of the Presentation Man¬ 
ager API that uses a technology called the System Object Model, or SOM. Part 
V of this book will give you the SOM and Workplace Shell basics you need to 
begin creating WPS apps. 

WPS reflects a change in the way programs are designed, as well as in how 
they’re programmed. Besides full chapters dedicated to WPS programming, 
you’ll find this book sprinkled with tips on how you would use (or not use) 
certain traditional PM features in a WPS-integrated program. 
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The Workplace Shed Versus the 
Presentation Manager 

In the early days of OS/2, most programming books concentrated on PM. It 
had been around longer than WPS and was better understood. (And it is eas¬ 
ier to write about than WPS because PM is structured more traditionally— 
but that’s an author’s secret, so don’t tell!) 

These days, of course, any book on OS/2 programming that deals strictly with 
traditional PM is only half a tutorial. WPS is one of OS/2’s strongest selling 
points. Because a user can take an object and drop it on the shredder, or on 
the printer, or in a folder—well, life begins to make a little more sense. 

As a result, the more WPS-enabled your programs are, the more progressive, 
the more hip they will seem—you’ll be hotter at parties than a film director 
for HBO! Figures 1-1 and 1-2 illustrate the sometimes radical difference 
between PM and WPS programs. 

Traditional PM programs often sport what is called a Multiple Document Inter¬ 
face (MDI). While an MDI application often contains many separate parts that 
are well integrated with each other under a common main window, it does 
not interact particularly well with the OS/2 system. 

An application like this makes you, the user, aware of the fact that you are 
RUNNING A PROGRAM. As Figure 1-1 shows, when you’re working in the Wat- 
com IDE, you know you’re working in the Watcom IDE. 

Contrast this with Figure 1-2, which shows version 2.1 of the WorkFrame/2. 
Hardly looks like a program, does it? It just looks like a folder with some 
icons in it, with one of the icon’s menus shown. 


This is a classic example of a WPS app. A WPS app works as much as possible 
within the capabilities already provided by OS/2. This is the ultimate com¬ 
mon look and feel—users may not even think of themselves as running a pro¬ 
gram, but rather as working with objects to perform a specific task. 



Actually, Figure 1-2 contains a number of Workplace Shell applications, all 
considerably easier to use than the WorkFrame/2. The most prominent WPS 
application on any OS/2 machine is the Desktop itself! And not only the Desk¬ 
top, but all the folders and objects on it are WPS applications. Some WPS 
applications, like program objects, can run other non-WPS or non-OS/2 pro¬ 
grams, as when you have an icon on your Desktop to run DOOM. 


But the actual object on the Desktop, be it program, data file, or printer, is 
itself a WPS application! 




The 

Watcom IDE 
— a tradi¬ 
tional PM 
program. 


Executing Log.. 


When a WPS app does open one or more windows, they are not layered as in 
an MDI application, but instead are free floating—ideally to be treated as sim¬ 
ilarly as possible to other system windows (like an open container object). 
The window should be highly aware of other system objects, allowing direct 
manipulation whenever feasible. (This is sometimes called a Single Document 
Interface, or SDL) 

Nonetheless, there’s only so much you can do with direct manipulation. 
(Imagine trying to write a document by arranging letters on a page.) There¬ 
fore, the bulk of most programs will still be built around the basic functions 
supplied by the PM API. 

So, even though WPS is very cool, Warp programming isn’t really an either/or 
situation: You can and will use both WPS and PM in building your applica- 
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Figore 1-2: The new WPS-enabled WorkFrame/2. 


tions. In this book, the early chapters deal with PM, because that’s the most 
straightforward way to learn about OS/2. Chapters 23 through 26 deal exclu¬ 
sively with the Workplace Shell. Nonetheless, there are three basic 
approaches to writing programs under OS/2, and you should keep them in 
mind while reading: 

i ^ Traditional applications in traditional environments are run by the user, 
who works with data exclusively through a program’s self-contained 
interface. Under DOS or under OS/2’s text mode, for example, a user 
would run a word processor program. All documents created by the 
word processor are interacted with exclusively through the word 
processor program. 

w* Traditional PM applications are run by the user, who also works with 
3 data exclusively through a program’s self-contained interface. But here 
® the user can run the program several times, or open the program 
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through associations made between the program and its data files. For 
example, an old-style PM word processor could be invoked multiple 
times by clicking on it, or by clicking on an icon representing a docu¬ 
ment created by that word processor. Data is shared between applica¬ 
tions through the use of the clipboard. 

WPS-integrated applications exist as objects on the Desktop, perfectly 
integrated with the rest of the operating system. Documents for a WPS 
word processor document can be created from within WPS by tearing 
off the appropriate template, or they can be printed by dragging the doc¬ 
ument object to the printer. It might even be possible to import one doc¬ 
ument into another by dragging the first document and dropping it on 
the second. Even when the word processor program proper is opened, it 
can interact with WPS objects. 



Note that a PM application can simulate WPS-like activities, but this turns out 
to be much more work than simply writing a WPS application, as you’ll see in 
Part V. 

In future chapters when I talk about PM programs, remember that WPS pro¬ 
grams are a special variety of PM programs, and so the discussion applies to 
both types. 


What Is the Launch Pad) 

You may wonder where the LaunchPad fits into all this talk about PM and WPS. 
What is the LaunchPad and what can you do with it? The LaunchPad is simply 
a program that is very well integrated with WPS, as shown in Figure 1-3. 


Figure 1-3: 

The rela¬ 
tionship of 
PM to WPS 
and the 
LaunchPad. 
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However you feel about the LaunchPad (some old-time OS/2 users don’t 
always like these new-fangled gadgets in their OS), you should be aware that 
some OS/2 users will be using it and liking it, and your program should be 
aware of its existence. What does that mean for you as a programmer? Well, 
not much really: It might be polite to ask new users of your program whether 
they want your program on the LaunchPad, and then place the program 
there if they so wish. 

Although placing an application on the LaunchPad is a relatively minor point, 
think how impressive your application will be if it integrates perfectly with 
WPS and the LaunchPad. Adding a little bit to each program to integrate it 
well certainly won’t hurt, and in some cases may help your application ingra¬ 
tiate itself with users. (A good thing.) 


Conclusion 

OS/2 is a real operating system enriched by a well-integrated, object-oriented 
graphical user interface; it's not just a graphical shell over a command-line- 
oriented interface. 

Programming for OS/2 involves understanding the Presentation Manager API, 
understanding the Workplace Shell, and understanding less visible but no 
less valuable features such as multitasking. 
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Understanding Warp Programs 

hi This Chapter 

The shift in the programming paradigm 
Events and queues 
Windows — what are they? 

Parenthood and ownership 
Bit masks and OS/2 data types 
OS/2 Make files 



In the beginning, the programmer was God, his Word was Law, and his Pro¬ 
grams made the people fall at his feet to worship... 

Although this bit of blasphemy is obvious hyperbole, not too long ago the 
whole subject of computers and programs was mysterious enough to the aver¬ 
age person—and to users—to afford programmers a certain exalted status by 
virtue of their mastery over the machine. In my mind, DOS illustrates the pinna¬ 
cle of user tolerance: Never have so many worked with so little for so long. 


There is a relevant point to this rant. It may have been okay in the old days to 
write a program where you requested user input through something like 


scanf("%s", someVar); 


and the whole world stopped and waited until you got the data you 
requested. Now, however, this is no longer true, although you can still write 
programs like this in OS/2 text mode, and OS/2 gives the user the power to 
switch from these kinds of programs at will. Users now expect that their 
wishes will come first, that your programs will respond immediately to all 
requests, and that your programs will handle behind-the-scenes business 
behind the scenes. 
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Everything's Such an Event With \lou 

This shift in the balance of computer world power is well illustrated by OS/2 
PM programs. In a PM program you never ever stop the flow of the operating 
system. A PM program loops continuously (for the duration of its run), ask¬ 
ing OS/2 for any events that may have occurred since the last time it asked. 

What’s an event? Well, basically anything that happens that the program can 
or should accept as user input or as an indication of how to act. Obvious 
events are things like the user pressing a key, the user clicking the mouse, 
even the mouse moving. Other less obvious events include things like the 
passing of a certain amount of time, the arrival of a signal from another part 
of the program to indicate that some task is finished, or the receipt of a notifi¬ 
cation that a floppy disk is full. 

OS/2 notifies you of events that have occurred via messages that it places in 
your application’s message queue. All PM applications have message queues 
that contain information about the events that have occurred and that they 
must handle in some fashion—by responding, as you might guess, appropri¬ 
ately to the event that triggered the message. 

Writing a program that revolves around user and system events is called 
event-driven programming. 

Sometimes you may decide to not handle certain events; for example, if the 
user merely moves the mouse. In any event, er, case, the messages in the 
queue become the prime movers of your code. In an event-driven program, 
you let users take control, and react to them. 

OS/2 handles a big portion of the details that surround events, thank good¬ 
ness, including things like determining which messages should end up in 
your application’s queue. 


Windows in OS/2? 

OS/2 programs are characterized by their windows. Every graphical OS/2 
application has some kind of window through which users issue commands 
(in the form of mouse clicks, key strokes, menu selections, and so on) to 
make known what they want done. 

As a programmer, you’ll create one or more windows, and then write special 
routines that handle the events for those windows. That’s OS/2 programming 
in a nutshell. Actually, that’s how programming in most GUIs is done. (See, 
this book has already paid for itself!) 
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Users think of a window as something like the Enhanced Editor shown in Figure 
2-1—you might, too, at this point. Notice that the figure labels the frame, the 
frame icon, the titlebar icon, the titlebar, the minimize and maximize icons, and 
the menu. All of these objects are also windows. They present something on 
screen and they have event handlers that cause specific actions to occur. 

The titlebar icon is sometimes called the system menu icon, m 

For example, double-clicking on the titlebar icon causes the application to 
close. Double-cEcking on the titlebar causes the application to maximize (fill 
the entire screen). The same user action has different effects depending on 
its context (that is, where the user positioned the mouse before clicking one 
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of its buttons): Clicking and dragging the edges of the frame window allows 
you to resize the frame window and all of its contents. If you click on a menu 
item window and drag it, another menu drops down, allowing you to select 
an item. 

Each of these windows has its own special message-processing routine 
(called a window procedure ) that causes it to act in a specific way. You don’t 
need to care much about this, except to know that it is a good thing. Your 
OS/2 apps won’t have to worry about providing basic capabilities, such as 
resizing and closing windows. All your application windows need to do is 
respond to the messages that directly affect them, or more accurately, the 
messages that directly affect the window’s class. 


OS/2 U/indoiVs Have Class! 

The concept of class is an important one in OS/2 programming. It’s borrowed 
from object-oriented programming (OOP) terminology, but you don’t need to 
know anything about OOP to understand this discussion or to write OS/2 pro¬ 
grams. 

OS/2 was designed not only to run multiple applications at once, but also to 
run several instances of the same application at the same time. As a result, if 
you adopt a subtle shift in the way you think about programming, it will be 
easier for you to write OS/2 applications. You don’t write OS/2 programs, 
really; you write special classes of windows that the user can invoke. You can 
even write special classes of windows that other programmers can use (for 
example, variations on the standard control types such as buttons or check 
boxes). 

If you’re writing a WPS application, this gets taken a step further: You actu¬ 
ally create one or more objects that are integrated into the system just like 
the standard objects. When installing your object, you can create a template. 
The user tears off a new object from the template and then either opens the 
object to invoke a more traditional type of application, or makes selections 
from the pop-up menu. 

A standard window, like the one shown in Figure 2-1, is actually a combina¬ 
tion of several classes of window, as discussed in the last section, including a 
frame window, a titlebar window, and so on. 

Each class is kind of like a self-contained mini program that exists to serve a 
specific purpose, and that always serves this purpose without knowledge of 
the larger application of which it is a part. In the next chapter, you’ll begin 
writing PM code, and your windows will have titlebars and frames that allow 
your windows to be moved and resized—but obviously those titlebars and 
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frames were programmed without knowledge of the applications that you 
build! 


Parenthood 


Windows on the Desktop have a location and a size. This is true of all win¬ 
dows, including the titlebar of a standard window, the icons on the Desktop, 
and so on. (Do I win an award for “Most Obvious Statement?”) 



The video screen consists of columns and rows numbered (in PM’s coordi¬ 
nate system) from 0 to whatever the screen resolution is. For a standard 
VGA, that would be 0 to a maximum of 639 for columns (width) and 0 to a 
maximum of 479 for rows (height). Coordinates are expressed as (X,Y), 
where X indicates the column and Y indicates the row. In Warp’s coordinate 
system (0,0) is always the bottom left-hand corner. (And, ergo, on a standard 
VGA (639,479) is the top right-hand corner.) 


Parenthood is a concept you may never have thought about in terms of PM 
programming, but which you probably have divined, nonetheless. The par¬ 
ent of a window determines where that window (the child window , as it is 
called) can display itself. You’ll sometimes read in these pages my reference 
to a window’s screen real estate , which is my way of referring to the total area 
of the screen a window may draw upon. A child is restricted to drawing 
within its parent’s real estate. 


From this we can logically conclude that all windows have a parent, since all 
windows need to have real estate to draw upon. The first window opened by 
an application usually has as its parent the Desktop. Any window that has 
the Desktop as its parent is called a top-level window. 


Other windows have top-level windows as parents. For an example of this, 
call up OS/2’s font dialog, usually found in the System Setup folder, which is 
in the OS/2 folder. ( The font dialog is shown in Figure 2-2.) At the bottom of 
this (and many of OS/2’s dialogs) you’ll find a couple of buttons. 

The dialog is the parent of the buttons; the buttons are the children. This 
relationship means that no matter what a program does, as long as the dialog 
is the parent, the buttons cannot draw themselves outside the dialog’s 
boundaries. You wouldn’t expect them to, now would you? Figure 2-3 shows 
what might happen if they could. 


There are two important logical consequences of the parent-child relation¬ 
ship. One is that if a parent window is hidden, all of its children are hidden. 
(What good would a disembodied button be, anyway?) The other is that the 
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Figure 2-3: 

When 
children go 
bad. (Not 
possible 
under OS/2.) 



coordinate system discussed in the previous technical stuff section is based 
on a window’s parent! 

So for top-level windows—windows that have the Desktop as a parent—(0,0) 
would be the bottom left-hand corner of the screen. But for other windows— 
like the titlebar or menu of a window—(0,0) is the bottom left-hand corner of 
that window! 

*1 


This is probably belaboring the obvious, but child windows generally appear 
to move with their parents. (Imagine moving the font dialog over a few pixels 
to the right and discovering that the buttons had remained at the same loca- 



This discussion of window coordinates also applies to the pointer (or mouse 
cursor, as it is sometimes called). Generally, when referring to the position of 
the pointer on the screen, a window determines the coordinates relative to 
its own lower left-hand corner. 
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tion on the screen.) In fact, a child window’s location doesn’t have to change 
at all because its location is relative to its parent’s lower left-hand corner. 

So, if a button is at (0,0) in its parent window, and the parent moves ten pix¬ 
els to the left, the button is still at (0,0) relative to its parent. It’s just that 
(0,0) now means something different in terms of an absolute (or global) loca¬ 
tion on the screen. Figure 2-4 illustrates this concept. 

In the last chapter I talked about old-style PM applications and, in particular, 
MDI applications. In an MDI application, the larger window is the parent of all 
the smaller windows. It is also usually the owner. (Ownership is discussed 
next.) 


Ownership 

Ownership expresses a chain of command: Owned windows pass messages 
to their owners in response to specific events. Often, owned windows are 
control windows (or just controls') that have a specific purpose. A common, 
probably obvious example of a control is a button. When you press an OK 
button, the button passes the OK message to its owner (usually a dialog), 
which then acts accordingly (usually by closing). A less obvious example of 
a control is the titlebar: When the titlebar receives a double-click event, it 
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passes a message to its owner telling it to maximize itself. When it receives a 
drag event, it tells its owner to move with the mouse. 

Parenthood and ownership are not mutually exclusive concepts. Often a 
window’s owner will also be its parent—for example, a button can be owned 
by a dialog and also be a child of that dialog. Also, while every window must 
have a parent (it is the parent that provides the screen real estate for the 
window to draw upon), ownership is optional. A window doesn’t have to 
answer to anyone. 


The Many Masks of OS/2 

A lot of OS/2 API calls are very short, really, consisting of only one or two 
parameters. Some unfortunately, consist of eight or more parameters. 

One of the things that makes some of the shorter calls possible, and keeps 
the longer calls from being even longer than they are, is the concept of bit 
masks or, as they are often called in OS/2, flags. 

The premise behind the flags concept is that many options may be specified 
as being either on or off. In computerese that translates very nicely to one or 
zero, of course. 

Rather than give each of these options its own parameter, as in: 

WinSomeFunc(int optl, int opt2, int opt3, int opt4); 

OS/2 uses a single data type (usually a 32-bit integer) and lets each of the bits 
represent a single option: 

WinSomeFunc(1ong opts); 

Rather than forcing you to memorize that the third bit from the left is paint¬ 
ing your window purple, OS/2 header files define each of the options with the 
correct value and you need to use only bitwise ANDs, ORs, and NOTs along 
with regular assignments to set options. For example: 

opts = COLORPURPLE; 

To specify any of a number of options, you would use a logical OR: 


opts = COLORPURPLE | TITLEROSE; 
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To turn off a specific option, you would use AND and NOT: 


opts = opts LAST IN LI ST; 



You don’t have to be particularly proficient in bit shuffling, but you should 
know what operators your language uses to obtain the correct result. 

If you’re using C or C++, you’d better know the difference between && and &. 
Most other languages, however, don’t distinguish between logical and bitwise 
operators. 


Wirth’s Revenge 



In the early ’70s, Niklaus Wirth created the Pascal language, based on a few 
simple premises. One of those premises was that a fundamental purpose of a 
compiler should be to catch obvious mistakes in data types. 

For example, if the programmer tries to increment a string or pass an integer 
to a procedure that requires a real parameter, the compiler should not allow 
this to occur. This is called type checking. About the same time that Pascal 
was invented, Dennis Ritchie invented the C language, based on the premise 
that it was none of the compiler’s business what the programmer wanted to 
do; it should just do it and damn the consequences. 


In the battle of the languages, C emerged the clear winner in the ’80s, but 
Wirth had his revenge: C has become a relatively strongly typed language, 
and its bloated stepson, C++, is extremely strongly typed. 

The point of this rant is that data type mania hit OS/2 and hit it hard. In some 
ways this is good, because it allows us to be relatively insulated from the 
mechanics of the OS/2 API. In other ways, it is bad, because it forces us to 
learn about a myriad of new data types. 

Some of these types are self-explanatory. ULONG and LONG, for example, are 
unsigned long and (signed) long integers. These are 32-bit integers, which are 
pretty much the staple data object of the OS/2 API. 

Some of them are less obvious, but not difficult. BOOL, for example, is short 
for Boolean, meaning a data type meant to hold either TRUE or FALSE. (TRUE 
is defined as a 1 and FALSE is defined as a 0). Again, BOOL is a 32-bit integer. 

Some of them are not obvious at all and are actually deliberately ambiguous. 
MPARAM is used sometimes as a pair of integers, sometimes as four one-byte 
fields, sometimes as pointers, and so on. So, even when the data type is used 
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to deliberately circumvent type checking, it has its own type. (Way down 
deep MPARAM is actually just a—you guessed it—32-bit integer.) 

There are some genuinely necessary data types, of course. OS/2 has a small 
fleet of data structures, which had to be defined to meaningfully convey any 
data at all. Often these data structures are huge , containing fifty or more 
fields. 


The main point of this section is to get you used to the idea of thinking of 
data types just as their specific data types. Don’t worry about what they are 
underneath, and for your own sake, don’t worry about memorizing every field 
in every data structure you come across. If you know what the essential pur¬ 
pose of a structure is, you can always examine its definition to see if it has a 
field for the information you want. 



OS/2 data types are defined with uppercase identifiers (for example, WIN- 
DOWDATA). Usually, data types are defined along with pointers to those 
specific types. The pointer types are uniformly P followed by the data type 
name (for example, PWINDOWDATA). 

I’m going to trust you to remember this so that 1 don’t have to constantly tell 
you things like, “PCHAR is a pointer to the CHAR type.” 


Command Line OS/2 Compilation 


Even if every marketing force in the world is pushing us toward GUIs, some¬ 
times it’s just easier to use a command line. 



If your compiler has an option to warn you when you haven’t prototyped a 
function, always set this option on! Always! 

Under OS/2 it is possible to compile and link a program successfully, only to 
have it fail when you run it. Without a header, a compiler will assume a 
specific linking format for a function, and that assumption could easily be 
wrong! 


So, for the IBM C/Set++ compiler, you always compile with the -Wpro option. 
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IBM C/Set++ 

To compile the sample programs using the IBM C/Set++ compiler, you need 
enter only the following at the command line: 

icc -Wpro /B"/PM:PM" progname.c 


Watcom C/C++ 10.0 

The Watcom compiler does not automatically invoke the linker, and can be 
used to compile programs for DOS and Windows as well, so the steps for 
compiling the example programs are slightly more involved: 

wcc -w4 progname.c 

wlink sys os2v2 pm op st=8192 FIL basic.obj 


Borland C++ for OS/2 

Although the Borland compiler will automatically invoke the linker, the linker 
options are somewhat involved and are probably easier to type as a separate 
command: 

bcc -c - Ic :\bcos2\include basic.c 
11 ink -aa -c -L\bcos2\lib \bcos2\lib\c02.obj 
basic, obj.basic.exe,,c2+os2 


Notes on C compilation in general 

Each of the compilers comes with its own .H files, as you might expect, but 
the .H files are not 100% compatible. If you have more than one OS/2 com¬ 
piler on your hard drive, you may run into path problems (so that one com¬ 
piler ends up trying to use the .H files from another). 

You can remedy this by including the paths on the command line (as I did 
with the Borland C++ example) or by setting up a simple .CMD file to set up 
the path based on which compiler you want to use. 

This also may cause a problem if you have an older version of a compiler and 
are trying to use it with the Warp Toolkit. Contact your vendor about .H file 
incompatibilities with the Warp Toolkit and your compiler. 
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Conclusion 

Once you have the main OS/2 concepts under your belt—events, messages, 
windows, window procedures, ownership, parenthood, and bit masks—you’ll 
find that OS/2 programming is a quite enjoyable exercise. You can get an 
amazing amount done just by accessing the power of OS/2. 

But the first step is a doozy—a little like having to push-start a diesel truck— 
and the next chapter is devoted to covering the basic OS/2 administration 
any application must handle. 



U IT STARTED OUT 45 A KIT, AND WHILE I MS WAITING RDR 
PARTS, THE y MERGED WITH A VACUUM CLEANER COMPANY." 




Chapter 3 


The Basic Application 
Framework Explained 

In This Chapter 

Essential OS/2 administration (OS/2 overhead) 

Client window procedures 

More on bit masks for setting options 


T he concept of application frameworks is probably as old as programming. 

In its crudest sense, a framework is a program that does nothing but han¬ 
dle the generic aspects of any application. 


If you were writing a program for a high-powered mainframe system, for 
example, there might be a level of security code that every program had to 
include just in order to run. 


What you might do, in that case, is have a program lying around that con¬ 
tained nothing but the code required for every program, and you would use 
this as a template for your programs, thus avoiding having to retype the 
same stuff over and over again and risk getting it wrong. 


This chapter introduces a basic application framework for an OS/2 applica¬ 
tion. We’ll be refining this framework occasionally as we progress. 



Do not, 1 repeat, DO NOT become obsessed with trying to memorize the func¬ 
tions and tables covered in this chapter. There is a lot of technical information 
in the upcoming pages, so just refer to this chapter later, when you need to. 

Just get the concepts presented: what do the calls do, why do they do it, 
where would you look if you wanted to change some aspect of the basic 
framework? That’s what you need to know, not how the sixth parameter of 
some function is used. 
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For the object-oriented among you, object-oriented frameworks such as the 
IBM Class Library User Interface, or ICLUI Q gesundheit /) allow you to reduce 
template code to just a few lines. 

These libraries can increase productivity quite a bit, but they are also inde¬ 
pendent of each other and of OS/2, so they aren’t necessarily a good way to 
learn OS/2 programming. 


The Basic Application framework 

Look now at the basic framework for just about every OS/2 Presentation Man¬ 
ager application, as shown in Listing 3-1. (For reasons we’ll discuss later, if 
you compile and run this program, the window that it creates will not be visi¬ 
ble until you select it from the task switcher.) 



The file 0S2.H contains all the special data types and function headers used 
in the program listing. Different languages will store this information in dif¬ 
ferent ways. 

The header file is set up to exclude certain API function definitions by 
default. This presumably has a positive impact on compile time. However, 
most of your OS/2 programs will use basic windowing calls and graphics pro¬ 
gramming interface calls, hence it is not a bad idea to start every program 
with the two define statements shown for INCL_WIN and INCL_GP1. 


Listing 3-1: The basic application framework. 


//define INCL_GPI 
//define INCL_WIN 
//include <os2.h> 

MRESULT EXPENTRY ClientWndProc(HWND, ULONG, MPARAM, PARAM); 

int main (void) 

{ 

HAB hab; /* anchor block handle */ 

HMQ hmq; /* message queue handle */ 

HWND hwndFrame, hwndClient;/* handles to windows */ 

QMSG qmsg; /* message queue */ 

char szClassNamef] = "Basic Framework"; 

ULONG f1CreateOpts = FCF_SIZEBORDER | FCF_SYSMENU | 
FCF_AUT0IC0N | FCF_TITLEBAR | 

FCF_MINMAX | FCF_TASKLIST | 

FCF_SHELLPOSITION ; 
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h a b = W i n I n i t i a 1 i z e (0); 

hmq = WinCreateMsgQueue(hab, 0); 

WinRegisterClass(hab, szClass Name, ClientWndProc, 

CS_SIZEREDRAW, 0); 

hwndFrame = WinCreateStdWindow(HWND_DESKTOP, 0L, 

&f1CreateOpts, szClassName, 
szWindowTitle, 0L, 0, 

0, &hwndClient); 

while (WinGetMsg(hab, &qmsg, 0, 0, 0)) 

WinDispatchMsg(hab, &qmsg); 

WinDestroyWindow(hwndFrame); 

WinDestroyMsgQueue(hmq); 

WinTerminate(hab); 
return 0; 

} 

/* This is the event handler for the window */ 

/* Currently, it does nothing */ 

MRESULT EXPENTRY ClientWndProc(HWND hwnd, ULONG msg, MPARAM mpl, 
MPARAM mp2) 

{ 

/*event handler*/ 
switch(msg) 
break; 

/*end event handlers */ 

/^default event handler */ 

return WinDefWindowProc(hwnd, msg, mpl, mp2) 


At first glance, even a simple PM program can look really horrible, and in a 
way it is. In order to make PM as flexible as possible, you must be able to 
specify a large number of options for many of the function calls. Hence, we 
end up with functions such as WinCreateStdWindow, which has nine parame¬ 
ters. (WinCreateStdWindow is, in fact, the short version of WinCreateWin- 
dow, which has thirteen parameters!) 

One way to minimize the horribleness is to just look at the function names 
and ignore the parameter lists. What’s left is pretty manageable, once we 
answer a few questions. 

I v" Winfnitialize 
^ WinCreateMsgQueue 
v* WinRegisterClass 
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u* WinCreateStdWindow 
is* WinGetMsg 
I v 0 WinDispatchMsg 
WinDestroyWindow 
v* WinDestroyMsgQueue 

1 

v* WinTerminate 

]S WinDefWindowProc (inside the event handler for the window) 



Notice that all the functions begin with the three letters Win. OS/2 API func¬ 
tions are (sort of) organized by grouping them into certain categories. Know¬ 
ing this can make digging through API references a lot easier. Window 
creation and management functions are specified with “Win.” Graphics pro¬ 
gramming interface (GPI) functions are specified with “Gpi.” 


Let’s look at each of these functions to see if we can make sense out of them. 
I’ll show the general form of each function as it would be written in C, and 
then I’ll show how the function is used in Listing 3-1. For example, to explain 
Winlnitialize, I would have this: 


General Form: HAB Winlniti al i ze(ULONG f 1 Options) ; 
As Used: hab = WinIniti al i ze(0); 


After the “General Form” and “As Used” examples, I’ll explain the purpose of 
the function. This way you can use this chapter as a reference to spot each 
function instantly and get an example of how it is used. (Pretty neat, eh?) The 
“General Form” is similar to what appears in the technical manuals, by the 
way, so this format will help make you feel at ease should you ever have to 
consult those voluminous tomes—er, really big books. 


Before looking at each function, however, we should get some idea of the big 
picture: What does WinCreateStdWindow do? 



If we were still just users, we could say, “Well, it creates a standard window, 
whatever that is.” But technically, a “standard window” is not just a single 
window. It’s a frame window (the border that surrounds all other windows) 
and possibly a number of other windows, such as the titlebar and the mini¬ 
mize and maximize icons. 

Chapter 2 explains what a window in OS/2 really is. 
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Most important of all to us as programmers is that WinCreateStdWindow cre¬ 
ates a client window, which is where almost all our application-specific text 
and graphics will appear. (Figure 3-1 labels the client window created for the 
enhanced editor.) 

It’s called a client window because, as application programmers, we are 
clients of OS/2’s Presentation Manager. 



i m 


File Edit Search Options Command Help 


j Top of File = 

itfdefine INCL_WIN 
j#define INCL_GPI 
#include <os2.h> 
jffinclude <string.h> 


iMRESULT EXPENTRY CIientWndProc(HWND, ULONG, MPARAM. MPARAM) 


HAB hab; /* anchor-block handle *7 

HMQ hmq; /*■ message queue handle */ 

HWND hwndFrame, hwndClient; /* handles to windows *7 

QMSG qmsg; message **/ 

char szCIassName[] = "Basic Framework"; 
char szWindowTitIe[] = "Basic Framework Window Title"; 
ULONG fIFrameOpts = FCF_STANDARD & ~FCF_ICON & 

~FCF_HENU & ~FCF_ACCELTABLE; 


hab = Winlnitialize(O); 

hmq = WinCreateMsgQueue(hab, 0); 

WinRegisterCIass(hab. szClassName, ClientWndProc. 
CS_SIZEREDRAW, 0]; 


hwndFrame = WinCreateStdWindow(HWND_DESKTOP, WS_VISIBLE. 

&fIFrameOpts, szClassName, 
szWindowTitie, 0L, 0. 0, 
ahwndCIient J; 

while (WinGetMsg(hab, aqmsg. 0. 0. 0)) 

WinDispatchMsg(hab, aqmsg); 


WinDest royWindow(hwndFrame) 
WinDest royMsgQueue(hmq); 
WinTerminate(hab); 
return 0; 


IMRESULT EXPENTRY CIientWndProc(HWND hwnd. ULONG msg. MPARAM mpl. MPARAM mp2) 


Line 2 of 61 Column 17 1 File Insert 


• j Lockup 


Shutdown Window list 


Figure 3-1: The "client" window in the Enhanced Editor. 


Winlnitialize, or Hold on to 
your Anchor! 

General Form: HAB Winlnitialize(ULONG flOptions); 
As Used: hab = Winlnitialize(0); 
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Winlnitialize is easy; this is your program saying to PM, “Hey! I’m going to be 
a PM program.” And PM comes back and says, “Here, you’ll need this.” Just 
when you’re expecting PM to throw you a life preserver, it throws you an 
anchor. Or more accurately, a handle to an anchor block. (This is the data 
type HAB, represented by the hab variable in the listing.) 

You’ll use your anchor block—which is simply an integer value that identifies 
your application to PM—to request certain services from the API, as seen in 
the calls to WinCreateMsgQueue, WinGetMsg, and WinDispatchMsg. 


Winlnitialize has one parameter and that parameter is always zero. 



Actually, the anchor block could probably be completely eliminated from 
OS/2 programming, as OS/2 has other ways to identify an application. But the 
anchor block has been retained to keep OS/2 compatible with other IBM 
operating systems, I’m told. 



I had to fight the temptation to give all the variables in this book longer, more 
memorable names than “hab” and “hmq.” I personally prefer “AnchorBlock- 
Handle” and “MessageQueueHandle” to the shorter names, and I dislike the 
common C practice of using case to distinguish between data types and vari¬ 
ables of that type, as in “HAB” and “hab.” 


However, these conventions are somewhat standard to OS/2 programs, so I’d 
be doing you a disservice if I followed my own preferences here. Since these 
shortened names are what you’ll see in most of the sample code you read, 
that’s the way they appear here. 


WinCreateMsgQueue, or 90°]o of Life 
Is Waiting in Line 

General Form: HMQ WinCreateMessageQueue(HAB hab, LONG IQueueSize); 
As Used: hmq = WinCreateMsgQueue(hab, 0); 

As I mentioned earlier, your application will have a message queue that will 
contain all the events that your application might respond to. The WinCre¬ 
ateMsgQueue call creates that message queue. It takes two parameters: the 
first is an anchor block and the second is the number of messages the queue 
should hold or zero to represent the default number, which is ten. 

If you have ten events (messages) waiting in your queue, and an eleventh mes¬ 
sage arrives, it is ignored. This means your applications must be able to han¬ 
dle messages fast enough to avoid having more than ten messages backed up. 
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But imagine typing this sentence into a word processor and having the word 
processor be ten characters behind what you’re typing! (The screen would 
still be showing “you’re” even though you’d finished the sentence.) Ten 
events are usually a lot to the user, and in most cases you shouldn’t have any 
trouble handling events fast enough to keep the queue pretty clean. 

Think of your window as a bureaucracy in an ideal universe: People still have 
to stand in line, but you want to get them through as fast as possible. 



If your application performs a lot of complex tasks that take enough time to 
make handling messages promptly a problem, you can place those tasks in 
their own threads. (This is covered in Chapter 22.) 

The data type returned by WinCreateMsgQueue is HMQ, a handle to a mes¬ 
sage queue—once again, an identifying integer. You’ll use this to request the 
events for your application, as shown in WinGetMsg and WinDispatchMsg. 


WinCreateStdWindow, or J fau Cad This 
the Simplified Version) 

General Form: HWND WinCreateStdWindow(HWND Parent, 

ULONG WindowStyle, PULONG CreateOptions , 

PSZ ClassName, PSZ WindowTitle, 

ULONG ClientStyle, HMODULE Resource, 

ULONG ResourcelD, HWND Client); 

As Used: hwndFrame = WinCreateStdWindow(HWND_DESKTOP, 

0L, &CreateOpts, szClassName, 
szWindowTitle, 0L, 0, 0, 

&hwndClient); 

We’re going to look at the calls a little bit out of order from the list presented 
earlier, because WinCreateStdWindow brings up a lot of issues that you need 
to understand before moving on to the next function, WinRegisterClass. 

This ugly beast (WinCreateStdWindow) creates a “standard window,” which 
as we saw earlier really comprises several windows. WinCreateStdWindow 
returns a handle to the frame window and assigns hwndClient the handle for 
the client window. 

Let’s look at each of WinCreateStdWindow’s parameters in turn. 
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|fou cm choose your parents! 

The first parameter in WinCreateStdWindow (HWND Parent) identifies the 
parent of the window being created. (Parenthood was covered in Chapter 2, 
remember?) 



Keep in mind that OS/2’s coordinate system considers (0,0) to represent the 
lower left-hand corner of the parent window. For a top-level window like the 
frame window, that would be the lower left-hand corner of the screen. For all 
the other windows, including our client window, (0,0) represents the lower 
left-hand corner of the frame window! 


Also remember that in OS/2, (0, 0) is the lower left-hand corner, nor the upper 
left, as in DOS and Windows. This isn’t just to be difficult, they tell me, but in 
fact makes sense from a mathematical standpoint. 


Windows and style 

Windows can be set to have any combination of various styles —options you 
use to change the behavior or appearance of the window. Table 3-1 shows all 


Table 3-1 Window Styles 

Style 

Meaning 

WS_AN1MATE 

"Explode" the window onto the screen. 

WS_CL1PCHILDREN 

Don't draw in child windows' areas. 

WS_CLIPSIBL!NGS 

Don't draw in sibling windows' areas. 

WS_DISABLED 

Don't react to keyboard or mouse input. 

WS.GROUP 

Indicates the first member of a group of windows. 

(See Chapter 12.) 

WSJVIAXIMIZED 

No effect! 

WSJV1INIMIZED 

No effect! 

WS_PARENTCLIP 

Don't draw outside the parent. 

WS_SAVEBITS 

Save image of what's underneath a window when the 
window first appears. 

WS_SYNCPAINT 

Force all painting messages to be handled immediately. 

WS_TABST0P 

Selectable via the tab key. (See Chapter 12.) 

WS_VISIBLE 

Be visible. 
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the possible styles for a window. When used in WinCreateStdWindow, these 
options indicate the initial state of the window. They can be changed during a 
window’s lifetime. 

The explanation of the last option, WS_VISIBLE, tells us why we had to select 
the running application from the Task List before we could see it. We didn’t 
select the WS_VISIBLE option for our window; therefore it wasn’t initially visi¬ 
ble. This shows that window styles can change. Change the WinCreateStd¬ 
Window call to: 

hwndFrame = WinCreateStdWindow(HWND_DESKTOP, WS_VISIBLE, 

&CreateOpts, szClassName, 
szWindowTitle, 0L, 0, 

0 , &hwndClient); 

Now, when you compile and run the program, the window will appear on 
screen, without you having to select it from the Task List. Of course, what it 
displays will seem kind of odd, but we’ll cover that later. A good thing to do 
now is to try out these styles in conjunction with the WS_VISIBLE style to see 
what effect they have. To do that you have to understand that while the WS_* 
symbols are 32-bit integers, they are used as bit masks. 

(If you have a good grasp on bit masks, as covered in the last chapter, you 
can skip this bit of technical stuff. This material is included here only as a 
review of the subject in the context of actual use.) 

As you know, computer data is all a series of zeros and ones. Usually when 
programming, we string a number of bits together and treat them as a unit, 
ignoring their bit value. (If you need the value 15, for example, you’re not 
likely to care that its bit value is “1111”.) But to keep functions from having 
parameter after parameter after parameter, related parameters are grouped 
together and treated as a string of bits. 

A window style is represented by a 32-bit integer, but you’ll never care what 
integer value that window style has. Instead you’ll look at the style as a bank 
of switches, either on or off, as shown in Figure 3-2. When you set 
WS_VISIBLE, you’re essentially turning the visible “feature” on, as shown in 
Figure 3-3. Now, the window style parameter will have an integer value of 
around -2 billion but, thankfully, we don’t care about that. We just deal with 
the individual bits, and then only in terms of their WS_* names. 

Because these bit masks are also integers it is possible to set options by 
adding them: 


windowOptions+WS_ANIMATE 
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You can also “unset” an option by subtracting it from the mask where it is 
set: 

windowOptions - WS_ANIMATE 

This is not advisable, however, because if the feature is already set and you 
add it again, or if the feature isn’t set and you subtract it, you won’t get the 
desired results. So, to set a feature use a bitwise OR: 


windowOptions | WS_ANIMATE 
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A bitwise OR says, “Turn this bit (or bits) on. If any of them are on already, 
leave them on.” 

To turn off a feature, use a bitwise AND NOT: 

windowOptions WS_ANIMATE 

A bitwise AND NOT says, “Turn this bit (or bits) off. If any of them are off 
already, leave them off.” 

You might also use a bit mask to represent a feature set that you use com¬ 
monly, or that you never want to use. We’ll use a bit mask in the next section 
on frame styles. 

WS_ANIMATE is one of the more immediately pleasing options you can set. It 
makes the window “explode” from the Desktop like the WPS folders do. (It 
will also play sound effects on a multimedia-enabled computer.) 

WS_CLIPCHILDREN, WS.CLIPSIBLINGS, and WSJPARENTCLIP all affect how 
the window draws itself. In theory, some applications are able to draw them¬ 
selves more rapidly with the right options set. 

WS_DISABLED causes the window to ignore all mouse and keyboard events. 

WS_GROUP and WS_TABSTOP are used by controls in dialogs (see Chapter 

12 ). 

You’d think a window with WIN_MAXIMIZE and WIN_MINIMIZE would 
appear maximized or minimized (respectively), but that doesn’t happen. 
WIN_MINIMIZE and WIN_MAXIMIZE are ignored by WinCreateStdWindow. 
Those wacky guys at IBM must have figured the WinCreateStdWindow call 
would be too simple unless they threw in some options that didn’t do any¬ 
thing. Seriously, though, these options probably did something way back in, 
say, OS/2 version 1.3. 

If you look back at WinCreateStdWindow, you’ll see that both the second and 
sixth parameters are style parameters. The second applies to the frame win¬ 
dow, the sixth to the client window. Although we’ve been discussing these 
options in terms of the frame window, many of them apply to the client win¬ 
dow as well. 


However, the client window inherits its styles from its parent, the frame win¬ 
dow, so you needn’t worry about specifying WS_VISIBLE for the client win¬ 
dow. In fact, you often won’t specify any options at all for the client window. 
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Creation options (let there he icons!) 

WinCreateStdWindow returns a frame window. This makes sense since the 
frame window is the main focus of standard window activities such as resiz¬ 
ing and maximizing. However, WinCreateStdWindow is especially handy 
because it can create several windows with one call. You specify which win¬ 
dows it should create through the third parameter, PULONG CreateOptions. 

Frames have a special relationship with the windows created with Win¬ 
CreateStdWindow: The frame is considered the owner of the other windows. 


You specify creation options through another 32-bit integer serving as a bit 
mask. Table 3-2 shows the possible options (or flags). (FCF stands for Frame 
Creation Flags.) 

You may specify any combination of these options, as with window styles 
(shown in the last section). Three of these options (FCF_ACCELTABLE, 
FCFJCON, and FCF_MENU) require data to be obtained from a resource file. 
(We’ll look at how to create resource files and how to use these options in 
Chapters 7 and 8.) Here are what these options tell WinCreateStdWindow 
about your standard window: 

FCF_ACCELTABLE: This tells WinCreateStdWindow that the window should 
have accelerator keys. Accelerator keys are usually “key chords” (two or 
more keys pressed at one time), such as Ctrl+Esc and Shift+End, which serve 
some special purpose in an application. (Before IBM and Microsoft got their 
hands on them, accelerator keys were called hot-keys by us ignorant masses, 
and that’s how I will continue to refer to them in this book.) 


FCF_AUT01C0N: Normally, a window will receive paint messages as long as it 
is active. These messages continue to be sent even if the window is mini¬ 
mized. I’m sure some people have a great reason for wanting to paint invisi¬ 
ble windows, but I generally set this option on. 



Actually, there is a good potential use for this, but it isn’t as common as it 
used to be because it affects only windows minimized to the Desktop. (The 
default is to minimize to the window viewer, and hence become essentially 
invisible.) A window minimized to the Desktop can draw on its iconized 
space. 


FCF.BORDER, FCF.DLGBORDER, FCF.SIZEBORDER: These options specify 
that the window should have a border. The first two specify that the window 
should not be resizable. A dialog border is thicker than a regular one, and the 
sizable border comes in only one thickness. 
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FCF_MAXBUTTON, FCF_MINBUTTON, FCF_HIDEBUTTON: The maximize and 
minimize buttons in a standard window are the two icons in the upper right- 
hand corner of the window that minimize and maximize an application. The 
hide button is a holdover from earlier versions of OS/2. It looks different 
than the minimize button but performs essentially the same function. 

FCF_HORZSCROLL, FCF_VERTSCROLL: These options add scroll bars along the 
bottom and right sides of the client window, respectively. Scroll bars allow the 
user to pan over a larger area of data than the window can display all at once. 

FCFJCON: When created, the window will be represented by an icon con¬ 
tained in a resource file. This icon will appear in the Minimized Window 
Viewer, and also as the system/titlebar menu icon. 

FCF_MENU: The window will have a menu bar, which appears under the title- 
bar. The actual contents of the menu bar created by this option must be 
described in a resource file. 

FCF_MOUSEALIGN: This option applies to dialog windows only, and indicates 
that the dialog will appear close to the mouse cursor’s location at the time of 
the dialog’s creation. 

FCF_NOBYTEALIGN: On some screen adapters, OS/2 can and will optimize 
(speed up) the displaying of a window by aligning it along byte boundaries. If 
this is not set it means you aren’t too fussy about the exact size or location of 
the window, because OS/2 will place it where the adapter can draw it quickly. 

FCF_NOMOVEWITHOWNER: Owned windows, as mentioned earlier, are not 
clipped to their owners, but usually move with them. You can make owned 
windows “free floating” by setting this option. 

FCF_SCREENALIGN: This option is used to position a dialog box relative to 
the screen, as opposed to positioning it relative to its owner. (Dialogs often 
look better if they are centered on the whole screen, as opposed to being 
centered over the window that owns them.) You don’t have to worry about 
this option now. 

FCFJSHELLPOSITION: By default, a window has a length and width of zero, 
and is positioned at (0,0). You can, after creating a window, set its size and 
location through the WinSetWindowPos function, or you can let WPS make 
those decisions for you. You can always change the location and size of a 
window later through WinSetWindowPos, regardless of whether this option 
was specified when the window was created. 

FCF_SYSMENU: With this option set, WinCreateStdWindow adds a window at 
the top left of the screen that, when clicked, drops down the system/titlebar 


menu. 
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FCF_SYSMODAL: The window will be created as a system modal window, 
which means that as long as it is on screen, the user will be able to do 
nothing else in PM. This is used for highly critical dialogs, as covered in 
Chapter 9. 

FCF_TASKLIST: Puts the title of the window (as shown in the titlebar) into the 
task list (accessed via Ctrl+Esc). 

FCF_TITLEBAR: Gives the window a titlebar. The titlebar can have text in it, 
which is specified in the fifth parameter of WinCreateStdWindow. 



As before, try altering Listing 3-1 to play with the various creation options. 

Some of these options, as noted in Table 3-2, apply only to dialogs, which are 
covered in Chapter 10. If you apply these to standard windows, nothing will 
happen. 



You can even try out the FCFJCON, FCFJMENU, and FCF_ACCELTABLE 
options. All that will happen is that the WinCreateStdWindow call will fail and 
the program will appear to do nothing. 

However, the program will remain active in memory and when you try to 
compile it again, you’ll be denied access to it. Since it won’t appear in the 
task list or anywhere on screen, you’ll need a special utility to kill it, or you’ll 
have to shut down your system and reboot. 


Most of the examples in the rest of this book use the FCF_STANDARD bit 
mask, with resource options turned off. 


ULONG f1FrameOpts = FCF_STANDARD & ~FCF_IC0N & 
~FCF_MENU & ~FCF_ACCELTABLE; 


The client elms 

WinCreateStdWindow creates several classes of window (see Chapter 2 for a 
discussion on window classes) including a frame window and a titlebar win¬ 
dow. The class name specified as the fourth parameter to WinCreateStd¬ 
Window (PSZ ClassName) is the class of the client window. 

This name is vital because OS/2 is going to use it to associate the client win¬ 
dow with an event handling procedure. That’s also why you have to register 
the window before creating it; the WinRegisterClass procedure is you intro¬ 
ducing OS/2 to your specific kind of window. 
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The remaining WinCreateStdWindow 
parameters 

The last four parameters to WinCreateStdWindow are, thankfully, fairly 
straightforward. 

The window title (PSZ WindowTitle) is the text that appears in the window’s 
titlebar, if it has one, and in the task list. 

The next two parameters, HMODULE Resource and ULONG ResourcelD, tell 
WinCreateStdWindow where to find the icon, menu, and accelerator table for 
the window, which were specified through the FCF_* options. We’ll look at 
resources in detail in Chapters 7 and 8, but the first of the parameters is like a 
file handle, and the second is a number used as an index into the resource file. 

The last parameter, HWND Client, is quite important, as WinCreateStdWin¬ 
dow makes it the handle to the client window. (Keep in mind that you are the 
client!) That’s where we’ll do all our drawing and where most of the events 
we have to handle will occur. 


WinRegisterCtass 


General Form: BOOL WinRegisterClass(HAB hab, 

PSZ pszClassName, PFNWP pfnWndProc, 
ULONG flStyle, ULONG cbWindowData); 


As Used: WinRegisterClass(hab, szClassName, 

ClientWndProc , CS_SIZEREDRAW, 0); 



In order for the operating system to send messages to a given window, or 
even to create a window of a specific class for that matter, it has to be made 
aware of the window class’s existence. The process of making the OS aware 
of the window is called registration, or registering the window. Because multi¬ 
ple instances of the same window can appear more than once on the Desk¬ 
top, you don’t really register a window—you register a window class. 

Remember that window classes also include such things as menus, icons, and 
even dialog controls. So, you may specifically write a window to be used by 
several different applications. 

For you to register a window, you must trot out your trusty anchor block 
(first parameter), and give that window a name (second parameter), and a 
function to handle events (third parameter). ClientWndProc is another one of 
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those “standard” names for the event handling function. You might want to 
name your functions more meaningfully. 

The window procedure , as ClientWndProc would be called, is invoked by PM 
in order to pass the procedure events. Because of this it must be an exported 
function. In C that means that the define EXPENTRY must be used in defining 
the function: 

MRESULT EXPENTRY WndPrc( . . . ); 

Other languages have different ways of doing this. 

The fourth parameter of WinRegisterClass is any combination of ten options, 
as shown in Table 3-3. Note that several of the options are the same as the 
window style options in Table 3-1. 

The only difference between the pairs of similar options is that the window 
styles (WS_*) apply only to the window created by that particular invocation 
of WinCreateStdWindow. A class style (CS_*) sets the default for all windows 
of that class. 


Table 3-3 Window Class Style Options 

Style 

Meaning 

CS_CLIPCHILDREN 

Don't draw in child windows' areas. 

CS_CLIPSIBLINGS 

Don't draw in sibling windows' areas. 

CS_FRAME 

The window is a frame. 

CS_HITTEST 

Notify the when mouse is moved. 

CSJVI OVEN CITIFY 

Notify when the parent is moved. 

CS_PARENTCUP 

Don't draw outside of the parent. 

CS_PUBLIC 

Allow the window to be used from any application. 

CS_SAVEBITS 

Save the image of what's underneath a window when the 
window first appears. 

CS_SIZEREDRAW 

Send a paint message when the window changes size. 

CS_SYNCPAINT 

Force all painting messages to be handled immediately. 


The only class style we’ll be using in this book is CS_SIZEREDRAW. 
CSJ5IZEREDRAW indicates that a window class must repaint itself whenever 
it is resized. 
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WinGetMsg and WinOispatchMsg 

General Form: BOOL WinGetMsg(HAB hab, PQMSG qmsg, 

HWND hwndFi1 ter, ULONG ulFirst, 

ULONG ulLast); 

General Form: MRESULT WinDispatchMsg(HAB hab, 

PQMSG qmsg); 

As Used: while (WinGetMsg(hab, &qmsg, 0, 0, 0)) 

WinDispatchMsg(hab, &qmsg); 

WinGetMsg asks OS/2 for a message pertaining to this application (specified 
by the anchor block handle) and waits until a message arrives. 



The QMSG structure looks like this 

|y w) 

typedef 

struct _QMSG { 


HWND 

hwnd; 


ULONG 

msg; 


MPARAM 

mpl; 


MPARAM 

mp2; 


ULONG 

ti me 


POINTL 

ptl ; 


ULONG 

reserved; 


} QMSG; 

typedef QMSG *PQMSG; 

The first four parameters should look mighty familiar because they are the 
four parameters that get passed to the window procedure. The time and ptl 
elements—containing the time the message was created and the location of 
the pointer at the time the message was created—are not directly available 
to ClientWndProc, but can be accessed by the window procedure through 
the API calls WinQueryMsgPos and WinQueryMsgTime. 

You usually won’t care about this information. 

You can be fussy about what kind of messages you’ll accept. For instance, if 
your application has several windows, you can specify in the third parameter 
that you want to accept messages that apply to only a certain window. 

The fourth and fifth parameters specify a range of messages to accept (or all 
messages if both are zero, as in Listing 3-1). Messages fall into particular cate¬ 
gories, and you can restrict the messages you want to process to keyboard 
only, or mouse only, or whatever. (The main types of messages are covered 
in Chapters 4, 5, and 6.) 
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Generally, all of the last three parameters will be zero. 

WinDispatchMsg seems to throw the message retrieved back into the ether. 
There are two questions that you might ask at this point. 

First, how the heck does the message get to the right window procedure? The 
answer is obvious: OS/2 puts it there. WinRegisterClass associates a class 
with a window procedure. When you call WinCreateStdWindow, you’re creat¬ 
ing an instance of that class—an actual screen window—that can receive 
messages. 


Second, if OS/2 is so smart, why do we have to bother with WinGetMsg and 
WinDispatchMsg at all? The answer to this one is less clear. This approach 
does allow greater flexibility: You don’t have to immediately dispatch mes¬ 
sages that you get. 



Frankly, however, I think that this loop is a leftover created by the hybrid 
nature of OS/2 PM programs. They are kind of object-oriented, but OS/2 is 
still procedure-based. 


A Workplace Shell object, by contrast, doesn’t require this loop, as you’ll see 
in Chapter 26. 


In this book, we’ll always be using this basic form of the loop in our non-WPS 
programs, though we will see ways of embellishing it (in Chapter 9). 


ClientWndProc and WinbefWindoutProc 

General Form: MRESULT WinDefWindowProc(HWND hwnd, 

ULONG msgID, MPARAM mpl, MPARAM mp2); 

As Used: return WinDefWindowProc(hwnd, msg, mpl, mp2); 

ClientWndProc is the function that you code to handle events specific to a 
given window class. It always has the parameters shown in Listing 3-1, and 
that format, you might well note, is the same as that for WinDefWindowProc. 

At the end of most client window procedures is a call to WinDefWindowProc. 
WinDefWindowProc gives a window its standard behavior. If you don’t have 
any reason to respond to a particular message, you can just let it pass 
through to WinDefWindowProc. 

If a window is supposed to have some default behavior to respond to that 
action, then WinDefWindowProc will perform the appropriate functions. If 
not, WinDefWindowProc just ignores the message. 
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Cleaning Up 

General Form: BOOL WinDestroyWindow(HWND hwnd); 

As Used: WinDestroyWindow(hwndFrame); 

General Form: BOOL WinDestroyMsgQueue(HMQ hmq); 

As Used: WinDestroyMsgQueue(hmq); 

General Form: BOOL WinTerminate(HAB hab); 

As Used: WinTerminate(hab); 

These three calls make up the clean-up code of any application. (WinDestroy- 
Window could also be used to remove a window after your app is finished 
with it.) 

These calls complement WinCreateWindow (WinCreateStdWindow, in this 
case), WinCreateMsgQueue, and Winlnitialize. They free up system resources 
that the other calls consumed. 

There really isn’t much more to say about them, for which I’m sure you are 
grateful, after wading through this chapter. 


Conclusion 

Let me emphasize again that it is not necessary for you to memorize the con¬ 
tents of this chapter. You’ll be surprised what you do come to know after 
writing a few PM apps, but there will probably be bits and pieces of this 
sequence of functions that don’t stick with you. 

That’s all right. (In fact, that’s probably healthy.) What’s important is 
whether you have grasped the concepts illustrated here. 

Do you understand (roughly) what a message queue is? What a window and 
its procedure are? Do you understand that a window’s procedure should han¬ 
dle the messages that it receives? 

If you do, you’ve got the foundation for building PM. Even if you’re shaky on 
parts of these concepts, you’ll find that they’ll become a lot more real to you 
as you continue with the examples in the rest of the book, and when you 
start building programs of your own. 


Onward! 



Chapter 4 


Getting Your Feet Wet and GUI 

In This Chapter 
The WM_PAINT message 
“Hello, World!” gets ugly 
Font basics 


C hapter 3 contained a long look at the basic application framework, which 
may have seemed somewhat discouraging to you: nearly fifty lines of 
code requiring extensive explanation that didn’t have the functionality of 
even the lowly “Hello, World!” program that most tutorials start with. It is at 
this point where many programmers new to OS/2 say, “Why bother?” and 
head back to DOS. 

While this may seem like a lot of overhead, it’s really pretty trivial consider¬ 
ing what you get in return: access to a common desktop that allows the user 
to run your application in conjunction with many others. 

We’re going to start off this chapter with a “Hello, World!” program, and it 
may not be very encouraging, either. It’ll show you the basics of drawing on 
an OS/2 window, and will give you your first taste of handling messages that 
OS/2 passes to your windows. But even this will seem complicated compared 
to the old text mode programs, where you just needed one line to write 
“Hello, World!” on the screen that your application dominated. 

That’s okay! No, really, it is! Because there’s one thing that you should learn 
and learn fast: Writing a PM program that’s modeled after an old text mode 
program is always going to be much harder. But if you’re going to do a text¬ 
mode style application, use OS/2’s text mode! 

There is a category of programs that require a lot of text display and input, of 
course, but wherever possible you should be designing your programs to dis¬ 
play graphically and to receive input through direct manipulation. (For text 
input and output, you should try to use 0S/2’s considerable library of con¬ 
trols, as covered in Chapters 11 through 17.) 
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“Hello, Worldl" Gets Uqty 

Listing 3-1 showed the basic “Hello, World!” program that we’re going to use 
to explore painting the screen. Notice that everything is the same before 
ClientWndProc, except the class name and title of the window. 



In this program the “#define INCL_GPI”, gives us access to the Graphics Pro¬ 
gramming Interface (GPI) defined in OS2.H, and is not optional. 

I also added STRING.H to get the basic string handling function strlen. 



To preserve space, and because the main part of the program won’t need to 
change, the listings after this show only Paintlt, which is called when the win¬ 
dow receives a message to paint itself. It would be somewhat inefficient to 
pass the data received by ClientWndProc as parameters to another function, 
but it does make the code considerably neater. 


#define INCL_GPI 
//define INCL_WIN 
//include <os2.h> 
//include <string.h> 


MRESULT EXPENTRY ClientWndProc(HWND, ULONG, MPARAM, MPARAM); 
MRESULT Paintlt(HWND); 


int main (void) 


HAB hab; /* anchor block handle */ 

HMQ hmq; /* message queue handle */ 

HWND hwndFrame, hwndClient;/* handles to windows */ 

QMSG qmsg; /* message */ 

char szClassName[] = "He!1oWorldl"; 
char szWindowTitle[] = "Yo! World!"; 

ULONG f1FrameOpts = FCF_STANDARD & ~FCF_IC0N & 
~FCF_MENU & ~FCF_ACCELTABLE; 


hab = Winlnitialize(0); 

hmq = WinCreateMsgQueue(hab, 0); 

WinRegisterClass(hab, szClassName, ClientWndProc, 
CS_SIZEREDRAW, 0); 

hwndFrame = WinCreateStdWindow(HWND_DESKTOP, 

WS_VISIBLE, &flFrameOpts, szClassName, 
szWindowTitle, 0L, 0, 0, &hwndClient); 
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while (WinGetMsg(hab, &qmsg, 0, 0, 0)) 
WinDispatchMsg(hab , &qmsg); 

WinDestroyWindow(hwndFrame); 

WinDestroyMsgQueue(hmq); 

WinTerminate(hab); 
return 0; 

} 


MRESULT EXPENTRY ClientWndProc(HWND hwnd, ULONG msg, MPARAM mpl, 
MPARAM mp2) 

{ 

/*event handler*/ 
switch(msg) { 
case WM_PAINT: 

PaintIt(hwnd); 
break; 

} 

/*end event handlers */ 

return WinDefWindowProc(hwnd, msg, mpl, mp2); 

} 


Here we see the ClientWndProc acting on a message type of WM_PAINT. As 
shown in the parameter list to ClientWndProc, the type of the message is 
passed as a 32-bit integer (or ULONG), which corresponds to some constant 
defined in OS2.H. 



WM_PAINT is one of the simpler messages that your application can receive, 
mpl and mp2 are not used in a WM_PAINT message, so you can disregard 
them. As a result, the Paintlt function takes only the handle of the window to 
be repainted. 

Generally, you should paint your window only when that window has 
received a WM_PAINT message. (The next chapter covers how to force a 
WM_PAINT message to occur.) ? 


Presentation spaces 101 

To start, let’s do something about the overall window. If you’ll recall, the 
basic application framework left the window to display whatever was in the 
background. Let’s clear out the entire window first: 

MRESULT Paint!t(HWND hwnd) 


HPS hps ; 
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RECTL rcl ; 

hps = Wi nBeginPaint(hwnd , NULLHANDLE, NULLHANDLE); 
WinQueryWindowRect(hwnd, &rcl ); 

Win FI 11 Rect(hps, &rcl , C L R_W HITE); 

WinEndPaint(hps); 
return 0; 


Remember that in PM, you don’t just draw willy-nilly on the screen. The 
whole point of creating a window in the first place is to have a place to dis¬ 
play your application’s data. But even when you have a window, you can’t 
draw directly on it. 

Instead, you need what is called a presentation space. A presentation space 
(or PS) is a data structure representing an abstract surface on which to draw. 
It also represents the qualities that certain drawing functions will take (such 
as color and line patterns). That’s the $75-an-hour explanation, anyway. In 
easier-to-digest terms, it’s a canvas for you to draw on, and brushes and 
other tools for you to draw with, that ultimately gets displayed on the device 
of your choice (screen, printer, plotter, whatever). 



There are three kinds of presentation spaces that you will be introduced to 
throughout the course of this book. The first and simplest kind of presenta¬ 
tion space is demonstrated by the previous code. You’ll learn about the other 
two kinds in Chapter 18. 


General Form: HPS WinBeginPaint(HWND hwnd, HPS hps, PRECTL prcl ) ; 
As Used: hps = WinBeginPaint(hwnd, NULLHANDLE, NULLHANDLE); 


You can create a PS first, and pass that to WinBeginPaint as the second para¬ 
meter. (We’ll explore the reasons for doing that in Chapter 18.) You can also 
specify by the last parameter that you want to draw only within a certain 
area of the window. (The PRECTL type is covered in the next section.) In the 
simplest cases, however, you’ll want WinBeginPaint to create the PS for you, 
and you’ll want to paint on the entire window, so you’ll specify both of these 
parameters as NULLHANDLE. 

A PS created by WinBeginPaint must ultimately be disposed of through 
WinEndPaint: 


General Form: BOOL WinEndPaint(HPS hps); 

As Used: WinEndPaint(hps); 

This is by far the simplest approach to drawing on a PM program’s window. 
A PS can be created and disposed of in the course of drawing the screen 
once, and this is appropriate for simple drawing tasks. It is also possible to 
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create a presentation space when a window is first created and use that 
space over and over again throughout the life of a window, only destroying it 
when the window closes. 



I’ve referred to handling events or messages several times already in this 
book, without really explaining what it means to “handle an event.” In most 
cases, it merely means making your window perform actions appropriate to 
the message it has received. 


In the case of a WM_PAINT message, however, you must, MUST call WinBegin- 
Paint and WinEndPaint, or PM will continually send you WM_PAINT mes¬ 
sages. Calling WinBeginPaint and WinEndPaint is what actually notifies PM 
that you have handled the WM_PAINT message. 


Rectangles 

What was nice about programming old style text-mode programs was that 
you could look at the screen as a series of columns and rows, where each 
intersection of a column and a row was one character cell. In a GUI, the 
columns and rows are still there, but the concept of the character cell is 
more or less meaningless. Every character occupies multiple rows and 
columns, and lining characters up horizontally and providing sufficient verti¬ 
cal space for them is no longer done automatically. 



Now, instead of drawing a string of text to a row, for example, we draw it to a 
rectangle. The rectangle represents some area of the screen (which may or 
may not be big enough to hold the text). 

Don’t forget that in OS/2, the lower left-hand corner is (0,0), not the upper left. 

Through an unfortunate abbreviation, the rectangle structure in OS/2 is 
called RECTL, and it looks like this: 


typedef struct _RECTL { 
LONG xLeft; 

LONG yBottom; 

LONG xRight; 

LONG yTop; 

} RECTL; 


typedef RECTL *PRECTL| 

As with all structures in the OS/2 API, a pointer to the type is declared as P 
followed by the structure name; hence PRECTL is another structure you’ll see 
a lot. 



52 


Part S From Square One (and Ground Zero!) 


If you were looking to clear the junk out of the window (painting over it, 
really) without the aid of this book, you’d probably come across the WinFill- 
Rect function first: 


General Form: WinFi11Rect(HPS hps, PRECTL prcl , LONG color); 
As Used: WinFi11Rect(hps, &rcl, CLR_WHITE); 



Okay: WinFillRect fills the rectangle (prcl) in the presentation space (hps) 
with a certain color (specified by the color parameter). 

Chapter 18 contains a list of color constants (CLR_*) you can use for this and 
other drawing functions. 

Now you need to figure out how to fill the entire window. When you have a 
question about something in your OS/2 program, usually the best thing to do 
is query. OS/2 functions that provide information usually begin with Query 
after the three-letter identifier (as in WinQueryWhatever or DevQueryWhat- 
ever). 


In this case, to find out the size of the window you have a handle for, you can 
use WinQueryWindowRect: 


General Form: WinQueryWindowRect(HWND hwnd, PRECTL prcl); 
As Used: WinQueryWindowRect(hwnd, &rcl ); 


WinQueryWindowRect will set the rectangle passed (prcl) to the dimensions 
of the window (hwnd). 




You could clear out the window with one call using GpiErase: 

General Form: GpiErase(HPS hps); 

But we’re going to be using the information from WinQueryWindowRect here, 
so we may as well use WinFillRect. 

In this case, the window handle is the client window—that is, everything 
below the titlebar (or menu, if there is one)—and not the entire frame 
window. 


It’s actually pretty easy to scan through the list of PM functions to find any 
given service that you might require for your application. However, if pro¬ 
gramming the PM API were just a matter of locating functions, there wouldn’t 
be so many books about it. 


PM is fairly consistent, and you’ll serve yourself best if you try to grasp the 
“big picture.” Learn the idioms and patterns as you go rather than trying to 
memorize the details. (I’ll be trying to point these patterns out to you, of 
course, as we progress.) 
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“Hello, World'!" at last / 

We’re now ready to write some text in the window. PM has an extensive set 
of tools to draw text in presentation spaces. The GPI functions allow you to 
rotate text, create three-dimensional effects, and do all kinds of flashy, movie- 
credit type stuff. 



That’s where I see most of those effects used, too: as opening or closing cred¬ 
its for an application, or to make flashy presentations. They aren’t critical to 
your understanding of PM or WPS, and studying them now will really bog you 
down with esoteric information. 

Chapters 18 and 19 deal with graphics and fonts in greater depth. 

Anyhow, here is the Paintlt method again, now modified to display “Hello, 
World!” in the center of the window. 


MRESULT PaintIt(HWND hwnd) 

{ 

HPS hps; 

RECTL rcl; 

char text[] = "Hello, World!"; 

hps = WinBeginPaint(hwnd, NULLHANDLE, NULLHANDLE); 

WinQueryWindowRect(hwnd, &rcl ) ; 

WinFi11Rect(hps , &rcl , CLR_BACKGROUND); 

WinDrawText(hps, -1, text, &rcl , 0, 0, DT_TEXTATTRS | DT_CENTER 
| DT_VCENTER); 

WinEndPaint(hps); 
return 0; 


Notice (and be thankful) that but one new method is introduced here: Win- 
DrawText. Although WinDrawText has a number of parameters, these are all 
pretty straightforward: 

General Form: LONG WinDrawText(HPS hps, LONG count, PCH text, 

PRECTL prcl, LONG clrFore, LONG clrBack, LONG flCmd); 

As Used: WinDrawText(hps, -1, text, &rcl , 0, 0, DT_TEXTATTRS | 
DT_CENTER | DT_VCENTER); 

This function draws on the presentation space (hps) a number of letters 
(count) from a string (text), in the rectangle specified (prcl). The text can 
have a foreground color (clrFore) and a background color (clrBack), 
although these options may be ignored based on flags set in flCmd. The 
background color is always ignored unless the presentation space has been 
set up to allow a different background for text than for the rest of the win- 
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dow. (More on this later.) WinDrawText returns the number of letters it actu¬ 
ally managed to draw in the specified rectangle. 

Just as OS/2 has a myriad of names for 32-bit integers, it also has a phone 
book of names for strings, such as PCHAR, PCH, PSZ, and even ASCIIZ. These 
are all compatible with the standard C string data type, however. 


Table 4-1 WinDrawText Commands 

Constant 

Meaning 

DT.BOTTOM 1 

Bottom-justify the text. 

DT_CENTER 2 

Horizontally center the text. 

DT_ERASERECT 

Clearthe area before writing. 

DT_EXTERNALLEADING 

Used for calculating the size of the rectangle needed 
to display text. 

DT_HALFTONE 

Display the text in halftone (that is, half as dark as 
usual). 

DT_LEFT 2 

Left-justify the text. 

DTJVINEMONIC 

Drawthe hot-keys. (The first character preceded by a 
tilde will be underlined.) 

DT_QUERYEXTENT 

Don't draw anything; just return the size of the 
rectangle necessary to draw the specified text. 

DT_RIGHT 2 

Right-justify the text. 

DT_STRIKEOUT 

Strike out the characters (that is, draw a line through 
them). 

DT_TEXTATTRS 

Draw text in the current colors specified by the 
presentation space. Ignore the foreColor and 
backColor options. 

DTJOP’ 

Top-justify the text. 

DT_UNDERSCORE 

Underscore the characters (that is, draw a line under 
them). 

DT_VCENTER' 

Vertically center the text. 

DTJ/VORDBREAK 

Don't draw partial words. 


1 DT_B0TT0M, DT_T0P, and DT_VCENTER are mutually exclusive. 

2 DT_CENTER, DT_LEFT, and DT_RIGHT and are mutually exclusive. 
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If the second parameter is specified as -1, WinDrawText understands that the 
third parameter is null-terminated and that it should draw everything until it 
encounters that null. 


And, no, despite what you may be thinking, WinDrawText draws text only in 
one straight row. You can call it multiple times to draw more, however, as 
you’ll see later. 

The LONG used as the last parameter is a bit mask which may have any of 
the values from Table 4-1 set. 



For “Hello, World!” I chose to center the text both vertically and horizontally. 
Also, I used the default colors for text for the presentation space. 

A presentation space isn’t just a canvas, you’ll recall, but also the brushes 
and styles, including text colors, used to paint that canvas. The default will 
probably be black on white, as I’ll explain in a minute. 


Actually, these are good parameters to play around with if you want instant 
gratification. You can change the justification of the text—although keep in 
mind that you can specify only one horizontal and one vertical justification 
for any given string. Specifying both DT_LEFT and DTJRIGHT will not justify 
your text on both sides. 


You can use DT_QUERYEXTENT to find out how large a rectangle you will 
need to display a string. This is the space required to prevent overlap with 
other lines. To prevent crowding with other text, you can specify DT_EXTER- 
NALLEADING, which expands the rectangle to allow for space over the let¬ 
ters. (In font terms, external leading is basically the distance from the top of 
the tallest letter possible to the bottom of the line above it.) 


DT_ERASERECT is good if you’re writing text multiple times over the same 
spot. DT_MNEMONIC is for indicating a hot-key to the user. The hot-key is 
indicated in the text string by the presence of a tilde (~). 



If you try to use DT_MNEMONIC for underlining more than one character in a 
string, by the way, you’ll discover that only the first character is underlined. 
All the other tildes in the string show up. In other words, “~H~e~l~l~o~!” 
comes out “H~e~l~l~o~!” 


Use the DT_UNDERSCORE option instead. 

A word in DT_WORDBREAK’s definition is delimited by a space, a carriage 
return, or a linefeed. WinDrawText always draws at least some part of at least 
one word. In other words, even if DTJWORDBREAK is specified, if you haven’t 
given enough space for a complete word WinDrawText will draw as much as 



Part I From Square One (and Ground Zero!) 


it can. (More on that in the next section, where we develop a long-winded 
“Hello, World!” program.) 


A brief took at colors 

In the preceding remember paragraph, I said that the default for text will 
probably be black on white. Why “probably?” Because the default for any 
given system depends on how the user has set up that system. 

In the predefined color schemes that come with Warp, black text on a white 
background is the most common setting. However, you can easily open up 
the color palette or color scheme objects in your System Setup folder to 
change the colors of any object you want. These changes can be for the 
entire system or just for a particular object. 

Therefore, by specifying the default, you don’t really know what will happen 
on a user’s system. But presumably users know and like their color scheme. 
Even though we’ve been using WinFillRect like this: 

WinFi11Rect(hps , &rcl , CLR_WHITE); 

We really should be using it like this: 

WinFi11Rect(hps, &rcl , CLR_BACKGROUND); 

This way the color of the window will be what the user has it set to, instead 
of always being white. (If users have gone to the trouble to set up a different 
color scheme than the default, you can assume they like that scheme and will 
appreciate the fact that you have respected it in your application. Or that 
they will revile you if you don’t!) 

Similarly, a presentation space has a palette or scheme of its own that deter¬ 
mines what colors certain objects will come out. There are specifications in 
the presentation space for the window interior, the text color (and font), and 
other things. 

By default, a presentation space assumes that the background of text should 
be transparent. (In other words, it shouldn’t be different from the window 
background.) In order to make the background text color of WinDrawText 
take effect, we need to call a GPI function, GpiSetBackMix. 

We won’t get into GpiSetBackMix in much detail here, but by passing the 
function a PS and a background mixing option, we can make the text from 
WinDrawText come out any color we like: 
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WinFi11Rect(hps, &rcl, CLR_BACKGROUND); 

GpiSetBackMixlhps, BM_0VERPAINT); /* add this line */ 

WinDrawTextlhps, -1, text, &rcl , CLR_RED, CLR_GREEN, DT_CENTER | 
DT_VCENTER); /^change this line */ 

Now both the CLR.RED and CLR_GREEN will take effect and the text will be 
drawn as red letters on a green background. 


“Hetto, World!" for the Long Winded 

The last section showed useful—even critical—aspects of OS/2 programming, 
but really, how likely are you to write an OS/2 program that shows just single 
lines of text in the middle of the screen? They do this in movies all the time- 
showing one string of text in a really large font spanning the screen. About 
the only time you see something like this in real life, however, is on an intro¬ 
duction screen, where the text is shown in a dramatic font with 3-D effects 
and animation. 

What we’ll do in this section is take the “Hello, World” program and show 
how it can be modified to print out more than one line of text. 

Once again, the changes we’ll make will appear in the Paintlt method. 

MRESULT PaintIt(HWND hwnd) 

{ 

HPS hps; 

RECTL rcl; 

/* text string should appear on one line */ 
char text[] = "Hello, World. Welcome to PresentationManager 
programming. In the Workplace Shell, large windows 
full of text are fairly rare."; 

/* text string should appear on one line */ 

LONG len, written, charHeight; 

FONTMETRICS fontMetrics; 

hps = WinBeginPaint(hwnd, NULLHANDLE, NULLHANDLE); 

WinQueryWindowRect(hwnd, &rcl); 

WinFi11Rect(hps, &rcl, CLR_WHITE); 

GpiQuery EontMetrics(hps, sizeof(FONTMETRICS), &fontMetrics); 
charHeight = fontMetrics.1MaxBaselineExt; 
rcl.yBottom = rcl.yTop-charHeight; 

1en = strlen(text); 

written = 0; 

while (written < len) { 
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written = written + WinDrawText(hps, -1, text+written, &rcl, 
0, 0, DT_TEXTATTRS | DT_WORDBREAK); 
rcl.yTop = rcl.yTop - charHeight; 
rcl.yBottom = rcl.yBottom - charHeight; 

} /* endwhile */ 

WinEndPaint(hps ); 
return 0; 


The initialization of the text variable, of course, should take place on one line 
in your source code—we just can’t fit it on a single line in this book. That’s 
the text we’re going to display. 

Looking at WinDrawText in this code, recall that it returns the number of 
characters it was able to print on-screen, and DT_WORDBREAK option that 
prevents WinDrawText from displaying a partial word. 

This is the loop that draws the text: 


1en = strlen(text); 

written = 0; 

while (written < len) { 

written = written + WinDrawText(hps, -1, text+written, &rc1, 0, 
0, DT_TEXTATTRS | DT_WORDBREAK); 
rcl.yTop = rcl.yTop - charHeight; 
rcl.yBottom = rcl.yBottom - charHeight; 

} /* endwhile */ 


We know we have to print out len characters, and at the beginning we know 
we’ve written out zero of those. Every time we call WinDrawText, we incre¬ 
ment written by the amount drawn and then, on the next pass through the 
loop, written becomes an index into text. 



In most languages, text+written, would be expressed as text[written] or 
substr(text, written, len-written), revealing that written is being used as a sub¬ 
script into the string of characters so that WinDrawText starts drawing 
where it last left off. In C, this is most easily expressed by the pointer arith¬ 
metic of text+written. 


At each pass, we change the bounding rectangle, so that it is lowered by the 
maximum height of the characters: 


rcl.yTop = rcl.yTop - charHeight; 

rcl.yBottom = rcl.yBottom - charHeight; 
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The higher on the screen, the higher the Y coordinate will be. Therefore, to 
lower a coordinate you subtract from it. Zero is the lowest visible point on 
the screen. 

Figure 4-1 shows how rcl changes on each pass. (The lines don’t actually 
appear. 



I deliberately ran the text “PresentationManager” together: Run this program 
and reduce the width of the window a bit. Notice that every resize results in 
the window redrawing itself and the Paintlt method is constantly rewriting 
and rewrapping the text around, so that the entire message appears in the 
window as long as there’s enough room vertically. 

Now reduce the width of the screen as far as possible. What happens to 
“PresentationManager?” It comes out “PresentationMa” on one line and 
“nager” on the next, or something similar to that. Look at Figure 4-2. 

Now shrink the window down as small as it will go, so that the entire message 
no longer fits on the screen. As I’m sure you expected, the text doesn’t break 
out of the window’s boundaries. You wouldn’t expect to see Figure 4-3, I’m 
sure. 
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Figure 4-2: 
DT_W0RD- 
BREAK 
encounters 
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word. 
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Figure 4-3: 
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But it does raise an important point: Why waste time drawing (or pretending 
to draw) what no one will see? We have, basically, two options when running 
out of vertical space. One option is to stop drawing after the top of the 
bounding rectangle gets to be less than zero. In the While loop, after sub¬ 
tracting from rcl.yTop and rcl.yBottom, we could add: 

if (rcl.yTop < 0) break; 

This change will look identical to the code that doesn’t exit the loop, because 
the last partial line will still be drawn. 

The other option is to not allow partial lines, by exiting the loop if the bottom 
of the rectangle ever goes off the screen: 
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if (rcl.yBottom < 0) break; 

Obviously, this is a judgment call. Some think that partial lines look sloppy; 
others feel they give a visual clue to the fact that there is more text. 

All in all, this is a not-too-difficult sample to read, but it does beg the ques¬ 
tion: How do we know what the maximum height of a character will be? 


Fonts: Making, your life easier 

In the old days of text programming, life was good: You had a screen divided 
up into (usually) 80 columns by 25 rows (80x25), and you knew that at any 
given location you could place exactly one character. Even a fancy text 
screen was never very complicated: All characters had the same height and 
same width. 


PM gives us a minimum of 640x480 pixels to deal with, and those pixels have 
to be arranged in some fashion to make characters. Aligning characters into 
even rows is trickier, because you can start, literally, anywhere on the 
screen. Columns aren’t exactly a cakewalk either, since the characters all 
take up different widths. You can even write at strange angles (for example, 
top-to-bottom, diagonally) and rotate characters however you like. 

The only reason that this is manageable at all is because of fonts. Fonts 
describe the qualities of a character set in terms that make it possible to not 
agonize over every single character you draw. 

PM has about a dozen calls that let you find out about and set fonts in your 
applications. For right now, we’ll just be looking at GpiQueryFontMetrics. 

General Form: BOOL GpiQueryFontMetrics(HPS hps, LONG size, 
PFONTMETRICS pfm) 

As Used: GpiQueryFontMetrics(hps, sizeof(FONTMETRICS), 

&fontMetrics); 



This function returns the metrics (that is, the measurements) of the font cur¬ 
rently in use by the presentation space passed as the first parameter. 

Again, remember that a presentation space isn’t just a space but also the cur¬ 
rent attributes that affect drawing in that space. One of those attributes is a 
font for drawing text. 


This function may seem odd because you have to pass the size of the font 
metrics structure to the function—which you would think should know how 
big the structure is. More wackiness on IBM’s part? 
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No. Because OS/2 changes and PM changes, the FONTMETRICS structure 
could change by having more fields added to it. By passing the size of the 
structure to the call, programs written for OS/2 version 3.0 will still work 
when OS/2 4.0 comes out, even if FONTMETRICS changes. 

We’ll see a lot of OS/2 structures that have a field indicating their size. 

Let’s look at two elements of the FONTMETRICS structure that might be used 
in a program like this. 


The first one, the maximum baseline extent, is quite useful: It tells you the 
total vertical space that a character in the font can take up. You might won¬ 
der why that’s not just called height, and we’ll go into that in Chapter 19. Let 
it suffice to say that in font terminology, height does not take into account 
things like letter tails (as on ay or a q). The maximum baseline extent is 
called IMaxBaselineExt in the FONTMETRICS structure: 


charHeight = fontMetrics.1MaxBaselineExt; 

We used this to adjust the bounding rectangle passed to WinDrawText: 

rcl .yTop = rcl.yTop - charHeight; 

rcl.yBottom = rcl.yBottom - charHeight; 

Table 4-1 listed an option called DT_EXTERNALLEADING. External leading is 
defined as the minimum blank space guaranteed between two lines of text. 
Guaranteed by whom? By the font’s designer, naturally. A font isn’t just a set 
of characters that look good. It’s also a large number of decisions that make 
strings of characters look good together . Those decisions are made by the 
person who creates the font. 

So, we probably should have also added the external leading to charHeight. 
OS/2’s system fonts may have an external leading of zero, so that’s not 
always crucial. 


Fonts: Complicating gonr life 

Some books on OS/2 programming spend a lot of time on fonts—sometimes 
relatively early in the book, too. However, the sentiment expressed by the 
long-winded version of “Hello, World!” is essentially accurate: In Workplace 
Shell programming, large screens full of text are relatively rare. 

There’s no getting around text information when you need it, which is why 
Chapter 19 goes into fonts in greater detail. At the same time, applications 
never need to worry about fancy text output, and the information you have 
here will suffice. 
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Besides which, the FONTMETRICS structure has over 50 elements, and it’s 
too soon to get bogged down in that level of detail. 

The largest body of text we’ll use in the sample programs in this book will be 
Help files, which are designed on a much larger scale than the individual 
position of each character. 


Conclusion 

Based on what we’ve learned in this chapter, it’s time to update the basic 
application framework. We’ll use this revised framework as the basis of our 
subsequent experiments, until we come up with an improvement on it. 

#define INCL_GPI 
//define INCL_WIN 
//include <os2.h> 

//include <string.h> 


MRESULT EXPENTRY ClientWndProc(HWND, ULONG, MPARAM, MPARAM ) ; 

int main (void) 

{ 

HAB hab; /* anchor block handle */ 

HMQ hmq; /* message queue handle */ 

HWND hwndFrame, hwndClient;/* handles to windows */ 

QMSG qmsg; /* message */ 

char szClassName[] = "Some Class Name"; 
char szWindowTitle[] = "Some Window Title"; 

ULONG f1FrameOpts = FCF_STANDARD & ~FCF_IC0N & 

~FCF_MENU & ~FCF_ACCELTABLE; 


hab = WinInitia 1iz e(0); 

hmq = WinCreateMsgQueue(hab, 0); 

WinRegisterClass(hab, szClassName, ClientWndProc, 

CS_SIZEREDRAW, 0); 

hwndFrame = Wi nCreateStdWi ndow( HWND__DESKTOP , WS_VISIBLE , 

&flFrameOpts, szClassName, 
szWindowTitle, 0L, 0, 0, 
&hwndClient); 

while (WinGetMsg(hab, &qmsg, 0, 0, 0)) 
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WinDispatchMsg(hab, &qmsg); 

WinDestroyWindow(hwndFrame); 

WinDestroyMsgQueue(hmq); 

WinTerminate(hab); 
return 0; 

} 


MRESULT EXPENTRY ClientWndProc(HWND hwnd, ULONG msg, MPARAM mpl, 
MPARAM mp2) 

{ 

HPS hps; 

RECTL rcl ; 

static HWND hwndPop; 

/*event handler*/ 
switch(msg) { 
case WM_PAINT: 

hps = WinBeginPaint(hwnd, NULLHANDLE, NULLHANDLE); 
WinQueryWindowRect(hwnd, &rcl); 

WinFi11RectChps, &rcl , CLR_WHITE); 

WinEndPaint(hps); 
return 0;} 

/*end event handlers */ 

return WinDefWindowProc(hwnd, msg, mpl, mp2); 

} 


The key things to remember about painting in PM are: 

f v* Paint only in response to a WM_PAINT message. 

1 ^ Handle WMJPAINT messages with WinBeginPaint and WinEndPaint. 

;' If you have a question about something in OS/2, you can find the answer 
§ to it with a query function. 

There’s a reason that programming books start with the “Hello, World!” pro¬ 
gram. Output is one of two vital functions any application must perform. 
Input is the other one. Stay tuned. (Read on!) 
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Of Mice and Messages 

in This Chapter 

p- Using window words to customize 
Forcing repaints 

;> Understanding message contents 
Handling mouse input 


J\ J ow ^ at we have at least some primitive means of drawing on the 
# W screen, it’s time to take a serious look at input. (We actually have dealt 
with some input already, in the form of the WM_PAINT message.) 

A program can have four basic sources of input: 


i * 0 The user 

v* The operating system or other programs 
u* Other parts of the same program 
Programmatic input, direct from us 


The last of these is probably the easiest to overlook, but we’ve already dealt 
with it. The messages we coded into the “Hello, World” program were basi¬ 
cally our direct input as programmers. The rest of this chapter deals with the 
other kinds of input, and related issues that arise in our explorations. And 
we’ll specifically look at the mouse as a source of user input. 

To start, we’re going to use a framework to create a new program, as in the last 
chapter. In this chapter, however, the paint message draws the contents of a 
text file that will contain a description of the messages our application 
receives. And, the presence of the text file makes it possible for us to react to 
commands by purging the file, opening a new file, or whatever. In short, it gives 
us a realistic context in which to work. We’ll call this the Events program. 
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Window/ Words 

One of the first topics that arise when trying to deal with input stems from 
the concept of window classes. (Remember them from Chapter 2?) Using 
WinRegisterClass, you introduce a window class and a procedure to handle 
messages for that class. No matter how many times the user runs your pro¬ 
gram, PM will always send the right messages to the right window. 

For example, if you had a window class that changed colors when the user 
clicked on it, and the user opened two of these windows at once, there would 
be no danger of one window accidentally influencing the color of the other. A 
mouse click message on the first window gets sent to only the first window, 
never to the second. 

Since you’ve written only one window procedure, you may wonder how that 
is possible. The answer lies in the HWND parameter, which is passed to the 
ClientWndProc. That contains the handle to the correct window, and most of 
your tasks are going to revolve around that HWND. 

However, there is only so much behavior that can be described purely in 
terms of a window’s physical appearance. Most of the time you will want to 
associate particular data with a window to reflect something about its state. 

A file viewer window, for example, might need to have data about what file is 
currently being displayed. A calendar window would require information 
about the month being displayed. And so on. 

The last parameter to WinRegisterClass, cbWindowdata, specifies an amount 
of memory to reserve for each instance of a particular class of window. These 
allotments of memory are called window words. 

Although the amount of memory reserved can be very large, in practice it is 
usually either zero bytes or four bytes (the size of a pointer). One reason for 
this is that although PM provides various ways to access a window’s words, 
those ways are neither very diverse nor flexible. It turns out to be easier (as 
well as more efficient) to simply allocate room for a pointer. 

To manipulate window words that contain pointers, we use WinSetWindow- 
Ptr and WinQueryWindowPtr. 

General Form: BOOL WinSetWindowPtr(HWND hwnd, LONG ndx, PVOID ptr) 
As Used: WinSetWindowPtr(hwnd, 0, event_file); 

General Form: PVOID WinQueryWindowPtr(HWND hwnd, LONG ndx) 

As Used: event_file = WinQueryWindowPtr(hwnd, 0); 

As the usage form suggests, we’re going to store a pointer to a file handle in 
the window words. The only question now is: When do we use these calls? 
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You will often see OS/2 programming books illustrate techniques using sta¬ 
tic local variables in the client window procedures. This use is frequently a 
bad idea because OS/2 code is re-entrant. In other words, ClientWndProc 
may call itself! 


Sometimes, in highlighting examples in this book, it is more expedient for me 
to use static variables rather than storing data in window words. That 
doesn’t mean that you should do this in your programs. (Do as I say, not as I 
do!) However, I have kept this to a minimum and will explain why the use is 
acceptable (or not) in a particular case. 


Starting Up and Winding bovtn 

When a window is created, PM sends a WM_CREATE message to the win¬ 
dow’s procedure. When you destroy a window, PM sends a WM_DESTROY 
message to the window’s procedure. That makes it possible for you to pre¬ 
pare your application before the window is actually displayed, and to “clean 
up” any resources that may still be in use. 

The EVENTS.C program, shown in Listing 5-1, takes advantage of these mes¬ 
sages by creating the text file used by the program upon receiving WM_CRE¬ 
ATE, and by destroying it upon the receipt of WM_DESTROY. There’s more to 
the listing than this, of course, as we’ll discover. 


Listing 5-1: The Events program (EVENTS.C). 


//define INCL_GPI 
//define INCL_WIN 
//include <os2.h> 

//include <string.h> 

//include <stdio.h> 

//include <errno.h> 

MRESULT EXPENTRY ClientWndProc(HWND, ULONG, MPARAM, MPARAM); 
MRESULT Paintlt(HWND); 

VOID Event(HWND, PSZ); 


typedef 
i nt 
i nt 
FILE 
char 
i nt 


struct { 
rowsperscreen; 
colsperscreen; 
*event_fi1e; 

*f i1ename; 
horz; 
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int vert; 
int maxhorz; 
} WINDOWDATA; 


typedef WINDOWDATA *PWINDOWDATA; 


int main 

{ 

HAB 

HMQ 

HWND 

QMSG 

char 

char 


(void) 

hab; 
hmq; 


/* anchor block handle 
/* message queue handle 


hwndFrame, hwndClient;/* handles to windows 

message 


*/ 

*/ 

*/ 

*/ 


qmsg; /* 

szClassName[] = "Events Program"; 
szWindowTitle[] = "Events"; 

ULONG flFrameOpts = (FCF_STANDARD & ~FCF_IC0N & 
~FCF_MENU & ~FCF_ACCELTABLE) 

I (FCF_HORZSCROLL I FCF_VERTSCROLL); 


hab = Winlnitialize(0); 

hmq = WinCreateMsgQueue(hab, 0); 

WinRegisterClass(hab, szClass Name, ClientWndProc, 

CS_SIZEREDRAW, sizeof (PWINDOWDATA)); 

hwndFrame = WinCreateStdWindow(HWND_DESKTOP, 

WS_VISIBLE, &flFrameOpts, szClassName, 

szWindowTitle, 0L, 0, 0,&hwndClient); 

while (WinGetMsg(hab, &qmsg, 0, 0, 0)) 

WinDispatchMsg(hab, &qmsg); 

WinDestroyWindow(hwndFrame); 

WinDestroyMsgQueueC hmq); 

WinTerminate(hab); 
return 0; 

} 


MRESULT EXPENTRY ClientWndProc(HWND hwnd, ULONG msg, MPARAM mpl, 
MPARAM mp2) 

{ 

char mouse_event[1000], metype[1000]; 

short flags; 

PWINDOWDATA wd; 

int vpos; 

MRESULT mr; 
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/*event handler*/ 
switch(msg) { 

case WM_CREATE: 

wd - (PWINDOWDATA)calloc(l, sizeof(WINDOWDATA)); 
WinSetWindowPtr(hwnd, 0, wd); 
wd->filename = strdup(tmpnam(NULL)); 
wd->event_fi1e = fopen(wd->fi1ename, "w"); 
Event(hwnd, "Create\n"); 
return 0; 

case WM_DESTROY: 

Event(hwnd, "Destroy\n"); 

wd = WinQueryWindowPtr(hwnd, 0); 

fcl ose(wd->event_fi1e); 

WinSetWindowPtr(hwnd, 0, NULL); 
return 0; 

case WM_PAINT: 

Event(hwnd, "Paint\n"); 
wd % WinQueryWindowPtr(hwnd, 0); 
ffl ush(wd->event_fi1e); 
return Paintlt(hwnd); 

default: 
break; 

} 

/*end event handlers */ 

return WinDefWindowProc(hwnd, msg, mpl, mp2); 


VOID Event(HWND hwnd, PSZ msg) 

{ 

PWINDOWDATA wd; 

wd = WinQueryWindowPtr(hwnd, 0); 
if (wd->event_fi1e != NULL) 

{ 

fputs(msg, wd->event_fi1e); 

WinlnvalidateRect(hwnd, NULL, FALSE); 


MRESULT Paintlt(HWND hwnd) 

{ 

HPS hps ; 

RECTL rcl ; 
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LONG charHeight; 

FONTMETRICS fontMetrics; 

FILE *paint_fi1e; 

char event_description[1000]; 

wd = WinQueryWindowPtr(hwnd, 0); 

fclose(wd->event_fi1e);/* necessary for IBM CSET++ */ 
paint_file = fopen(wd->fi1ename, "r"); 

hps = WinBeginPaint(hwnd, NULLHANDLE, NULLHANDLE); 

WinQueryWindowRect(hwnd, &rcl ); 

WinFi11Rect(hps, &rc! , CLR_WHITE); 

GpiQueryFontMetrics(hps, sizeof(fontMetrics), &fontMetrics); 
charHeight = fontMetrics.1MaxBaselineExt; 

if (paint_file!=NULL) { 

WinQueryWindowPos(hwnd, &swp); 
wd->rowsperscreen = swp.cy / charHeight; 
wd->colsperscreen = swp.cx / fontMetrics.1Emlnc; 

rcl.yBottom = rcl.yfop-charHeight; 


do { 

fgets(event_description, 1000, paint_fi1e); 
if (feof(paint_fi1e)) break; 

WinDrawText(hps, strlen(event_description)-1, 
event_description, &rcl , 0, 0, DT_TEXTATTRS); 
rcl.yTop = rcl.yTop - charHeight; 
rcl.yBottom = rcl.yBottom - charHeight; 

} while (rcl.yBottom >= 0); 

fcl ose(paint_fi1e); 

} 

wd->event_fi1e = fopen(wd->fi1ename, "a"); /* nec. for IBM 
CSet++ */ 

WinEndPaint(hps ); 

return 0; 



The WINDOWDATA structure contains all the information we’ll need to make 
the Events program work, and more. We won’t use most of the fields until 
Chapter 6. 
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Notice that once again I have placed a lot of code in separate functions. In 
this chapter, most of the code we add is going to be in ClientWndProc itself. 
As a result, IVe kept the Paintlt function, and there is some inefficiency since 
several message handlers are forced to query the window word. 

It isn’t necessary to use the WM_CREATE and WM_DESTROY messages to set 
up windows and clean up after them. In fact, you could set up your windows 
right after creating them: 

hwndFrame = WinCreateStdWindow(HWND_DESKTOP, 

WinSetWindowPtr(hwndClient, 0, event_file); 

and then clean up after the WinGetMsg/WinDispatchMsg loop, but before 
destroying the windows: 

event_file = WinQueryWindowPtr(hwnd, 0); 
fclose(event_fi1e); 

WinDestroyWindow(hwndFrame)* 

I personally prefer to keep the main function as small as possible. Since I’m 
inclined to write more object-oriented programs, I tend to take the attitude 
that if a function belongs to a window class, it should be in the window pro¬ 
cedure (or in a function called by the window procedure, of course). 

I snuck in one new API call here, to figure out the window’s size: 

General Form: BOOL WinQueryWindowPos(HWND hwnd, PSWP pswp); 

As Used: WinQueryWindowPos(hwnd, &swp) 

This call returns the position and size of the data in a pointer to the SWP 
structure. For now, the only elements of SWP that interest us are cx and cy, 
which are the width and height of the window, respectively. 

WinQueryWindowPos(hwnd, &swp); /*new*/ 

rowsperscreen = swp.cy / charHeight; /*new*/ 

colsperscreen = swp.cx / fontMetrics.1Emlnc; /*new*/ 

Backstage at the Events Program 

The flow of the Events window procedure is: 

1 u* Create the text file. 

1 u* When an event occurs, write it to the text file. 
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After writing to the text file, force a repaint. 
v* When a paint message arrives, display the current text file on screen. 
is* Close the text file. 


We’ve covered creating the text file. Writing to a text file is a basic function of 
most computer languages—nothing OS/2-specific there. 

Forcing the window to repaint, however, is an important technique to master, 
because as a general rule you aren’t going to be doing any drawing unless 
you’ve received a WM_PAINT message (as we discussed in Chapter 4). So, if 
you know the window needs to be updated, you want to be able to force that 
message to be sent. 

The method for forcing a repaint is WinlnvalidateRect: 

General Form: BOOL WinlnvalidateRect(HWND hwnd, PRECTL rcl, BOOL 
InvalidateChi1dren) 

As Used: Wi nlnval idateRect(hwnd, NULL, FALSE); 

The first parameter (HWND hwnd) indicates the window you want invali¬ 
dated, the second (PRECTL rcl) gives the precise area you want invalidated 
(or NULL for the entire window), and the last (BOOL InvalidateChildren) tells 
PM to force all the window’s children to repaint as well. 

That’s really the only new PM stuff introduced here. We’re going to examine 
the messages our application receives by having the message handlers call 
the Event function. Note that even the WM_PAINT message gets added to the 
Events text file. 


First the message gets written to the text file, then the text file is flushed so 
that all the data is there for the Paintlt function to use. In the Paintlt function 
we open another handle to the same file, so that we don’t disturb the state of 
the file pointer stored in the window words. 



This trick works with Watcom’s C compiler, but IBM’s C compiler returns a 
“file already open” error when you attempt to use fopen on an open file. 
Hence there are extra lines in the code to close and reopen the text file han¬ 
dle stored in the WINDOWDATA struct. 


Understanding PM Messages 

Crucial to programming in PM is an understanding of how messages work, 
which is why this Events program is a good example. We will at once be 
examining the nature of the messages and, in a limited way, acting on them, 
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Figure 5-1: 
The many 
shapes of 
MPARAM. 


which is more or less how you would go about writing a real PM program—or 
a program for just about any GUI. 

Let’s look again at the parameter list for any window procedure: 

ClientWndProc(HWND hwnd, ULONG msg, MPARAM mpl, MPARAM mp2) 

The hwnd parameter is, of course, the handle of the window receiving the 
message, and msg is one of any number of constants such as WM_PAINT, 
WM_CREATE, or WM_DESTROY. Those three messages can be acted upon 
without any more data, but some messages clearly require more information 
than a long integer can provide. 

Obvious examples include a mouse click or a keypress: often you want to 
know where the mouse was clicked or which key was pressed. That’s where 
mpl and mp2 come in. 

MPARAM is, in essence, just another four-byte integer, but it isn’t always 
treated as such. (There are a ton of names for four-byte integers in OS/2. This 
is supposed to be good for strict typing, but mostly seems to be good for con¬ 
fusing beginners.) 

When OS/2 wants to give you some additional information about a message, 
it uses the combined eight bytes of mpl and mp2 to store that information. It 
uses them in many different ways, as Figure 5-1 suggests. 
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The rather annoying prospect of having to fish elements out of these fields is 
mitigated by the presence of certain C macros (or special functions in other 
languages) that handle the extraction for you. 

To illustrate, let’s look at a simple addition we can make to the Events pro¬ 
gram’s ClientWndProc to catch the WM_ACTIVATE event. 

A window receives an activate event on two occasions: when it is activated 
and when it is deactivated. The information is stored in the first short integer 
of mpl. 

case WM_ACTIVATE: 

if (SHORTlFROMMP(mpl)) Event(hwnd, "ACTIVATED\n"); 
else Event(hwnd, "DEACTIVATEDXn"); 
break; 

If this short integer contains a value of 1, the window is being activated; oth¬ 
erwise it is being deactivated. 

Try it out. Pretty cool, eh? By using this simple program to capture events 
and by evaluating their contents, you can get a solid grasp on the mechanics 
of PM programming. 

Now that we’ve learned how to capture a simple event, let’s take this discus¬ 
sion up a notch, and look at a more complex event. 


The Mighty Mouse 

One category of messages is related to the pointing device. For most people, 
that’s a mouse, but it can also be a trackball, pen, touch pad (my preference), 
touch screen, or any other pointing device recognized by OS/2. I’ll be refer¬ 
ring to the device as “the mouse,” but you can take that to include mouse 
substitutes as well. 

There are six basic mouse messages to cover: clicking, double-clicking, motion 
starting, motion ending, button up, and button down. There are three sets of 
these messages, one for each mouse button PM recognizes. There is also a 
message that indicates that the mouse has moved with no buttons down. 

So the complete set of basic mouse messages is BUTTONxCLICK, BUTTONxD- 
BLCLK, BUTTONxMOTIONSTART, BUTTONxMOTIONEND, BUTTONxUP, and 
BUTTONxDOWN, where x is replaced by either 1, 2, or 3. 

To get a feel for these messages, let’s add a message handler to Events to 
handle BUTTON1DOWN: 
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case WM_BUTT0N1D0WN: 

Event(hwnd, "Button 1 Down\n"); 
break; 


Now run the Events program, position the mouse cursor on the window, and 
click the primary button. Your window receives (and displays) a WM_BUT- 
TON1DOWN message. 



The primary button is the left one for most folks, but the mouse buttons can 
be reconfigured with the mouse object in the System Setup folder (usually 
contained in the OS/2 system folder). 

Even though I swap buttons depending on which hand I’m using with the 
mouse, I tend to refer to the primary mouse button as the left mouse button, 
so don’t be surprised if you see that here and in other computer books. The 
important thing to remember is that a BUTTON 1 something message can 
occur from either the left or the right button, but that’s not something you 
have to worry about. 


Click outside the window. No surprise: The window receives a deactivation 
message but no WM_BUTTONlDOWN. Move the cursor back inside the win¬ 
dow, press the primary button and hold it down. The window receives a sin¬ 
gle WM_BUTTONlDOWN message. Double-click the primary button and—the 
window receives a single WM_BUTTONlDOWN message! Now, click the pri¬ 
mary button, wait for a moment, then click it again and the window will 
receive two WM_BUTTONlDOWN messages. 


Surprised? PM differentiates between two single clicks and a double-click. 
Notice, however, that a double-click does result in at least one WMJBUT- 
TONxDOWN message. 


At the first click, PM can’t know whether or not it’s going to be a double-click 
message, and doesn’t hold on to the message to find out. If you click the but¬ 
ton rapidly, like a double-click, but move the mouse in between the clicks, 
you’ll discover that your window does get two WM_BUTTONlDOWN mes¬ 
sages. More on this later. 



You may want to remove the call to the Events function from the WM_PAINT 
handler, since the WM_PAINT message is going to seem obvious and redun¬ 
dant. But don’t do it just yet! There may yet be some value in determining 
when the WM_PAINT messages get sent relative to other messages! 


Mouse information 

By far the most likely question you’d have about any mouse event is: Where 
was the mouse when the event happened? The mpl parameter contains this 
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information, and you can extract it with the SHORT 1FROMMP and 
SHORT2FROMMP macros. 

Declare a local character array called mouse_event and try the following 
code: 

case WM_BUTT0N1D0WN : 

sprintf(mouse_event, "Button 1 down at %d, %d\n", 

SH0RT1FROMMP(mpl), 

SH0RT2FROMMP(mpl)); 

Event(hwnd, mouse_event); 
break; 

The Events program will now print out not only the BUTTON1DOWN event, 
but also the location of the event. 

If you run this, you’ll discover that the pointer coordinates are given, pre¬ 
dictably, relative to the lower left-hand corner of the window that the event 
occurred in. That’s generally what you’ll want. 


More basic mouse events 

Let’s examine the remaining mouse events in detail by setting up a big switch 
statement to catch all those events and handle them together. 

/* mouse messages */ 

case WM_BUTT0N1D0WN: 
case WM_BUTT0N1CLICK: 
case WM_BUTT0N1DBLCLK: 
case WM_BUTT0N1UP: 
case WM_BUTT0N1M0TI0NSTART: 
case WM_BUTT0N1M0TI0NEND: 

case WM_BUTT0N2D0WN: 
case WM_BUTT0N2CLICK: 
case WM_BUTT0N2DBLCLK: 
case WM_BUTT0N2UP: 
case WM_BUTT0N2M0TI0NSTART: 
case WM_BUTT0N2M0TI0NEND: 

switch(msg) { 

case WM_BUTT0N1D0WN: 

strcpy(metype, "Button 1 down"); 
break; 

case WM_BUTT0N1CLICK: 
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strcpy(metype, "Button 1 click"); 
break; 

case WM_BUTT0N1DBLCLK: 

strcpy(metype, "Button 1 double-click"); 
break; 

case WM_BUTT0N1UP: 

strcpy(metype, "Button 1 up"); 
break; 

case WM_BUTT0N1M0TI0NSTART: 

strcpy(metype, "Button 1 motion start"); 
break; 

case WM_BUTT0N1M0TI0NEND: 

strcpy(metype, "Button 1 motion end"); 
break; 

case WM_BUTT0N2D0WN: 

strcpy(metype, "Button 2 down"); 
break; 

case WM_BUTT0N2CLICK: 

strcpy(metype, "Button 2 click"); 
break; 

case WM_BUTT0N2DBLCLK: 

strcpy(metype, "Button 2 double-click"); 
break; 

case WM_BUTT0N2UP: 

strcpy(metype, "Button 2 up"); 
break; 

case WM_BUTT0N2M0TI0NSTART: 

strcpy(metype, "Button 2 motion start"); 
break; 

case WM_BUTT0N2M0TI0NEND : 

strcpy(metype, "Button 2 motion end"); 
break; 

} 


sprintf(mouse_event, "%s at %d, %d\n", metype, 

SH0RT1FROMMP(mpl), 

SHORT2FROMMP(mpl)) ; 

Event(hwnd, mouse_event); 
break; 

The switch-inside-a-switch statement is used to supply a string description of 
the event that occurred so that the same code can be used for all the mes¬ 
sages. The same code is then used to establish the coordinates. 

This is important code to try out, because it can give you the details about 
what mouse events occur under what circumstances. Using this code is going 
to create a far greater impression on you than any explanation you read 
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about what happens when. Not only that, you can keep the Events program 
around to refresh your memory should you decide to handle mouse events 
directly. 

For example, if you press a mouse button and hold it, and then press another 
mouse button, does the second click register? (Yes.) What if you then move 
the mouse? Do you get a motion start message for the first button pressed or 
for the second or for both? (For the first only.) 

It isn’t necessary in many cases to handle mouse events, and in some cases it 
is undesirable to do so, as I’ll explain shortly. 


Events that miqht he mousey 

There are several other types of messages that can occur due to mouse activ¬ 
ity. For example, the mouse user could click on a button or menu and from 
that create a command (that is, a WM_COMMAND message, which we’ll 
examine in greater detail in the next chapter). 

We’ll look now at another set of messages that can occur because of the 
mouse, but not exclusively. These are events normally associated with WPS 
that can all be activated through keystrokes or the context menu of the 
object being manipulated. 

The events are: 

u* 

u* 

is* 

I 


I 

is* 

1 

These messages (WMJBEGINDRAG, WM_ENDDRAG, WMJSINGLESELECT, 
WM_BEGINSELECT, WM_ENDSELECT, WM.OPEN, WM_CONTEXTMENU, and 
WM_TEXTEDIT) use mpl and mp2 in the same way. mpl is the location of the 
pointer at the time of the event, and mp2 is TRUE if the message was gener¬ 
ated by a mouse event or FALSE if it was generated by a keyboard event. 


Starting and stopping a drag (associated with dragging the secondary 
button) 

Selecting a single object (associated with clicking the primary button) 

Starting and stopping a multiple selection (associated with dragging the 
primary mouse button) 

Opening an object (associated with double-clicking on an object) 

Requesting a context menu (associated with clicking the secondary but¬ 
ton) 

Requesting a text edit (associated with clicking the secondary button 
while pressing the Alt key) 



Here’s a case block to handle these events: 



Chapter 5 Of Mice and Messages 


case WM_BEGINDRAG: 
case WM_ENDDRAG: 
case WM_SINGLESELECT: 
case WM_BEGINSELECT: 
case WM_ENDSELECT: 
case WM_0PEN: 
case WM_TEXTEDIT: 
case WM_CONTEXTMENU: 

switch(msg) { 

case WM_BEGINDRAG: strcpy(metype, "Begin Drag"); break; 
case WM_ENDDRAG: strcpy(metype, "End Drag"); break; 
case WM_SINGLESELECT: strcpy(metype, " Select"); break; 
case WM_BEGINSELECT: strcpy(metype, "Begin Sel"); break; 
case WM_ENDSELECT: strcpy(metype, "End Select"); break; 
case WM_0PEN: strcpy(metype, "Open"); break; 
case WM_TEXTEDIT: strcpy(metype, "Edit"); break; 
case WM_CONTEXTMENU: strcpy(metype, "Popup Menu");break; 
} 


sprintf(mouse_event, "%s at %d, %d\n", metype, 

SH0RT1FROMMP(mpl), 

SH0RT2FR0MMP(mpl)); 

Event(hwnd, mouse_event); 
break; 

This is very important to try out. What happens now if you click the mouse 
on your window? In addition to BUTTON messages, you get messages indicat¬ 
ing the tasks with which certain mouse actions are commonly associated. 

Not only that, if you press Shift+FlO, you’ll discover that you get a WM_CON- 
TEXTMENU. From our point of view as application programmers, it’s gener¬ 
ally preferable to use these function-oriented messages rather than 
processing mouse events directly, as I’ll discuss in greater detail in the next 
section. 



A true WPS application—one that is integrated fully into the Workplace 
Shell—doesn’t even process these messages. Instead, it either accepts the 
default behavior for WPS objects or overrides the methods used to implement 
those features. 


More on this in Chapters 24, 25, and 26. 
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When to use Which mouse messages 

From these little experiments in mouse handling we can ascertain a few 
important details about PM and WPS programming: 

is* Actual WPS objects can reduce the amount of direct mouse handling 
S needed by accepting default WPS behaviors for certain messages. 

is* Actual WPS objects can respond by overriding certain inherited behav- 
I iors, again without responding directly to mouse messages. 

1 

is* For non-WPS windows, the program can respond to requests for certain 
features (like dragging, or displaying a context menu) instead of 

responding directly to mouse messages, creating a WPS-like feel. 

I 

\s* For non-standard tasks, the program must handle the mouse directly. 

Whenever possible then, we should use the WPS messages, resorting to the 
BUTTONxEVENT-type messages only when absolutely necessary. 

It’s a bad idea in many ways to try simulating WPS features through PM code. 
For example, if you want to allow direct editing of an object in your PM-based 
program, you might intercept the BUTT0N1 CLICK event and check to see if 
the Alt key is depressed, and respond by allowing editing if it is. 

But one of the features of the Mouse object in the System Setup folder allows 
the user to customize what mouse actions perform what events. Users could, 
for example, decide that Ctrl+Mouse Button 1 is a text edit command on their 
system. You don’t want your program to defy those wishes. 

Sometimes you’re stuck. If you have a text editor and you want to allow the 
user to drag and drop text, for example, you may find that the easiest and 
best solution is to incorporate that functionality into your main program. 
Also, you may have some specific functionality that WPS doesn’t account for 
(such as swapping two selected objects). But as a rule, get as much use as 
you can out of PM and WPS. 


Conclusion 

The mouse is actually more difficult to handle than the keyboard, as you’ll 
see in the next chapter. Nonetheless, even if you handle the mouse directly, it 
really isn’t too hard. 

What a relief, eh? You were probably thinking you’d find gargantuan function 
calls the whole way through this book! 
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In This Chapter 

. Handling keyboard messages 

Understanding important system events 
i Using scroll bars 
s Accessing owned windows 
Setting system Timers 


f he long lecture you just received on capturing mouse events applies, 
believe it or not, to the keyboard as well! If you really want to build good 
applications, you will make them keyboard accessible as well as mouse 
accessible. But if you can deal with user-generated commands (such as “open 
a file” or “do this action”), that’s superior to trying to catch every keystroke. 
(User-generated commands can be created from menus, by the way. This is 
covered in Chapter 7.) 

However, you should know how to handle keyboard messages, or rather, the 
keyboard message. Yes, there is only one! And it’s pretty straightforward: 

The WM_CHAR message tells you that a key has been pressed. 

Now, if you’ve programmed under DOS or similar character-based environ¬ 
ments, you may rightly feel that this is an inadequate description. After all, 
under DOS there were many functions that reportedly returned a keypress, 
but left a lot to be desired in terms of what information they passed. An Alt 
keypress for example, never registered unless it was pressed in conjunction 
with another key. 

The Presentation Manager creates a message for every keypress—and more. 
Add this to the Events program’s message handler and give it a try: 

case WM_CHAR: 

Event(hwndKey press!"); 
break; 
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Note well that the Alt key, the Ctrl key, the Scroll Lock key — every key—cre¬ 
ates an event under PM. What you may find disturbing is that most keys cre¬ 
ate two events. 


As Dorothy might say, “Toto, I don’t think we’re in Kansas anymore.” A text- 
based environment like DOS wants to know what keys the user has pressed, 
and so concerns itself with that. A GUI-based environment like PM, on the 
other hand, wants to know a lot more: 


I is* Has a key been pressed? 
i* Was the key pressed previously (for auto-repeat)? 
is* Is the key being released? 
is* Are the Shift, Alt, and/or Ctrl keys down, too? 

is* Were any other keys pressed and released between the time this one 
was pressed and released? 

is* Is this key special in some way? 

A WM_CHAR message contains all that information. The first short integer in 
mpl contains some combination of the bits in Table 6-1, set. 


mpl also contains, in the second short, two single-byte integer values repre¬ 
senting the repetitions that a held-down key has generated since the last key 
message was processed, and the raw scan code of the pressed key. 



In C, of course, the single-byte integer data type is the char. Hence, the 
macros to retrieve information out of a single byte of an MPARAM are called 
CHAR1FROMMP, CHAR2FROMMP, CHAR3FROMMP, and CHAR4FROMMP. 

mp2 contains the character code in the first short and the virtual key code in 
the second short. The virtual key code can be compared to a list of defines 
(VK_*) to establish which key was pressed. These are fairly self explanatory: 
VK_TAB, VK_UP, and so on. 


Let’s put this information to use in the Events program started in Chapter 5: 


/* keyboard messages */ 
case WM_CHAR: 

Event(hwnd,"Key: "); 
flags = SH0RT1FROMMP(mpl); 


/* basic key info */ 

if (flags & KC_KEYUP) Event(hwnd, "Up "); 

else if (flags & KC_PREVDOWN) Event(hwnd, "Auto "); 

else Event(hwnd, "Down "); 

if (flags & KC_LONEKEY) Event(hwnd, "- Lone Key - "); 
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Table 6=1 WM_ 

CHAR Flags in SHORT1 of mpl 

Constant identifier 

Significance 

KC_ALT 

The Alt key was down. 

KC_CHAR' 

The key is a valid character. 

KC_C0MP0SITE 2 

The key is a combination of the current key and the 
previous dead key. 

KC_CTRL 

The Ctrl key was down. 

KC_DEADKEY 2 

A dead key (used in conjunction with the next key to 
create a special character). 

KCJNVALIDCOMP 2 

The previous dead key and the current key don't make 
a valid combination. 

KC_KEYUP 

The key is being released. 

KC_LONEKEY 

No other keys were pressed or released between the 
time this key was pressed and released. 

KC_PREVDOWN 

Auto-repeat message. (The key is being held down.) 

KC_SCANCODE' 

The key has a valid scan code. 

KC_SHIFT 

The Shift key was down. 

KC_VIRTUALKEY 

The key is not a displayable character (as in a 
function key or an Alt+key combination). 


Generally set; might be invalid if the message has come from not from the keyboard 
but from another program. 

2 Used with only certain keyboards. 


/* which key */ 

if (flags & KC_VIRTUALKEY) 

switch(SH0RT2FR0MMP(mp2)) { 

case VK_ALT: Event(hwnd, "(Alt) "); break; 

case VK_ESC: Event(hwnd, "(Esc) "); break; 

case VK_F1: Event(hwnd, "(FI) "); break; 


case VK_TAB: Event(hwnd, "(Tab) "); break; 

case VK_UP: Event(hwnd, "(Up) "); break; 

} else { 

metype[0] ** ' ( ' ; 





86 


Part f From Square One (and Ground Zero!) 


metype[l] = 
metype[2] = 
metype[3] = 
metype[4] = 
Event(hwnd, 
} 


SH0RT1FR0MMP(mp2); 
')'; 


' \ 0 ' ; 
metype); 


sprintf(metype , " Reps: #%d", CHAR3FR0MMP(mpl)); 
Event(hwnd, metype); 


i f 
if 
if 


(flags & KC_SHI FT) Event(hwnd, " -> Shift"); 

(flags & KC_CTRL) Event(hwnd, " -> Ctrl"); 
(flags & KC_ALT) Event(hwnd, " -> Alt"); 



Event(hwnd, "\n"); 
break; 

You might want to change the Event function to call WinlnvalidateRect only 
when the newline character (‘\n’) is detected. 

Having done this, we’ve created an interesting situation: We quickly run out 
of room to view all the events that have occurred. We’ll cover what to do 
about that in the next section! 


I didn’t show the entire block of VK_* possibilities here because I’m sure you 
get the point. The VK_* constants are pretty straightforward: 


V K_A LT 

VK_ALTGRAF 

VK_BREAK 

VK_CAPSLOCK 

VK_CTRL 

VK_DELETE 

VK_D0WN 

VK_BACKSPACE 

VK_BACKTAB 

VK_END 

VK_ENTER 

VK_ESC 

V K_FI 

VK_F2 

VK_F3 

VK_F4 

LO 

U_ 

1 

V K_F6 

VK_F7 

VK_F8 

VK_F9 

V K_F10 

V K_F11 

VK_F12 

VK_H0ME 

VK_INSERT 

VK_LEFT 

V K_N EW LINE 

VK_NUMLOCK 

VK_PAGEDOWN 

VK_PAGEUP 

VK_PAUSE 

VK_PRINTSCRN 

VK_RIGHT 

VK_SCRLLOCK 

V K_SHI FT 

V K_SPACE 

VK_SYSRQ 

VK_TAB 

VK_UP 


AltGraf is apparently available on some keyboards. (I’ve never seen it.) Also, 
the VK_Fn constants go up to VK_F20, but I didn’t include those here because 
most keyboards don’t have twenty function keys. 

Important System Events 

We’ve already established uses for WM_CREATE, WM_DESTROY, and 
WM_PAINT. We’ve registered WM_ACTIVATE, and it probably doesn’t take 



Chapter 6 Input! More Input! 



much imagination to figure out how that particular message might be used. If 
we were running a game, for example, we might freeze play when the window 
was deactivated. 


There are other system events that are good to know about and that we’ll 
just mention briefly here: WM_CLOSE, WMSHOW, and WM_SIZE. 


V WM_CLOSE closes the window. It has no associated data. If passed to 
I WinDefWindowProc, WinDefWindowProc posts a WM_QUIT message to 
the application. You might want to handle this by confirming the user’s 
intention. The pros and cons of using WM_CLOSE are discussed in Chap- 
1 ter 9. 

^ WMJSHOW indicates a change in the visibility of a window. The first 
| short in mpl contains TRUE if the window is to be shown, or FALSE if it 

j is to be hidden. (This does not include being covered. That is you can’t 

j see a window if it’s covered, but that’s not the same as being invisible.) 

^ WM_SIZE indicates that the window has changed size, mpl contains the 
j °ld size; mp2 contains the new size. WinCreateWindow (and WinCreate- 
! StdWindow) create this message, as does user resizing. 



In this book, I basically use WinQueryWindowRect to determine the size of 
the window when I need it. You can keep track of the window’s size, however, 
by monitoring the WM_SIZE messages. This approach is more efficient and 
just a little more work. 


We’ll be using these messages and others throughout the rest of the book. 
Now let s see if we can’t resolve the Events program’s problem of having too 
much data to fit on one screen. 


Scroll Bars 

Two of the FCF_* options you can specify in WinCreateStdWindow 
(described in Chapter 3) are FCF_HORZSCROLL and FCF_VERTSCROLL. Let’s 
add those to Events: 

ULONG f1FrameOpts = (FCF_STANDARD & ~FCF_ICON & 

~FCF_MENU & ~FCF_ACCELTABLE) 

| (FCF_H0RZSCR0LL | FCF_VERTSCROLL); 

If you run Events now, you’ll see that the Events window does indeed have 
scroll bars, but you’ve probably done enough programming to realize that 
nothing in life is this easy. Sure enough, clicking on the scroll bars has no 
effect. 
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Using scroll bars requires us to take a number of steps: 

I v 0 Set the scroll bars to have a range appropriate to the data we’re trying 
to display. 

Handle messages about changes to the scroll bar. 

v 0 Use our knowledge of the current scroll bar position to change what we 
paint on the window. 

Before we even look at these steps, though, we have to find out how we’re 
going to access the scroll bars. Presumably they’re windows, too, like any 
others, so we need some way to find out what their handles are. 


Tracking, down relations 

Two functions are invaluable in getting window handles: WinQueryWindow 
and WinWindowFromID. 

General Form: HWND WinQueryWindow(HWND hwnd, LONG relation); 

As Used: frame = WinQueryWindow(hwnd, QW_PARENT); 

General Form: HWND WinWindowFromID(HWND hwnd, LONG id); 

As Used: sbh = WinWindowFromlD(frame, FID_H0RZSCR0LL); 

WinQueryWindow returns, as the second parameter, the handle of a window 
that has a relationship to the window passed as the first parameter. Although 
this relationship may be any one of several (designated by the QW_* set of 
defines), we’re just going to concern ourselves here with QW_PARENT. 

As the name suggests, QW_PARENT causes WinQueryWindow to return the 
parent of the window passed as the first parameter. The parent of the client 
window is the frame. 

With a handle to a window, you can ask for a handle to any of its children. (So 
far only the frame has owned any other windows, but as you’ll see in the next 
part of this book, any window can own other windows.) You ask based on the 
child window’s identification number. 

Now all you need to know is what that ID number is. Well, any given window 
can be set up to have an arbitrary number of windows with arbitrary IDs, but 
WinCreateStdWindow creates a frame window that knows all of the following 
defines: 

FID_CLIENT FID_H0RZSCR0LL FID_MENU FID_MINMAX 

FID_MENU FID_SYSMENU FID_TITLEBAR FID_VERTSCROLL 
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Working, With scrott bars 

Once we have the handles to the scroll bars, it just remains for us to take the 
three steps outlined previously to set them, respond to them, and modify the 
way they are painted. 

To set a scroll bar window, you send a message to that window through the 
WinSendMsg function: 

General Form: MRESULT WinSendMsg(HWND hwnd, ULONG msg, MPARAM mpl, 
MPARAM mp2); 

As Used: WinSendMsg(sbh, SBM_SETSCROLLBAR, 

MPFROMSHORT(currenth), 

MPFR0M2SH0RT(1, maxhorz)); 

Notice the format of WinSendMsg: it’s the same as ClientWndProc, which 
makes sense because the scroll bar window has to handle messages we send 
just as it has to handle messages sent by OS/2. 

WinSendMsg illustrates the third type of input listed at the beginning of 
Chapter 5: one part of a program sending input to another part of the same 
program. When writing your own PM programs, you’ll find this a handy fea¬ 
ture. 



The result type from WinSendMsg is MRESULT, which is YATBI (Yet Another 
Thirty-two Bit Integer). You won’t usually care about MRESULT’s 32-bit value, 
but instead will use a series of helper macros (SHORT 1FROMMR, 
SHORT2FROMMR, and so forth) to get the information returned by the 
window. 


The SBM_* series of defines is used by the scroll bar window class. 
SBM_SETSCROLLBAR is used to cause the scroll bar to set its range and posi¬ 
tion. The position is set by the first short of mpl, the low bound is set by the 
first short of mp2, and the high bound is set by the second short of mp2. 



The MPFROMSHORT and MPFROM2SHORT macros turn short integers into 
an MP, which keeps us from having to declare a local variable to hold the 
scroll bar range values. Other languages have different ways of handling 
this. 


Because SBM_SETSCROLLBAR changes the range and position of the slider, 
we’ll have to query the current position of the slider every time we want to’ 
expand it, so that we don’t constantly reset it back to zero. Here’s what the 
new Event function looks like: 


VOID Event(HWND hwnd, PSZ msg) 
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SHORT 

char 

HWND 

PWINDOWDATA 


currentv, currenth; 
debug[1000]; 
frame, sbh, sbv; 
wd; 


wd = WinQueryWindowPtr(hwnd, 0); 

frame = WinQueryWindow(hwnd, QW_PARENT); 

sbh = WinWindowFromID(frame, FID_H0RZSCR0LL); 

sbv = WinWindowFromID(frame, FID_VERTSCROLL); 

currenth = SHORTlFROMMR(WinSendMsg(sbh, SBM_QUERYPOS, 0,0)); 

currentv = SHORTlFROMMR(WinSendMsg(sbv, SBM_QUERYPOS, 0,0)); 

wd->horz = wd->horz + strlen(msg); 

/* if this is a new line, calculate the largest text 
line passed and see if we should expand the range 
of the horizontal scroll bar. 

Expand the range of the vertical scroll bar*/ 

if (msg[strlen(msg)-l]== , \n') { 
wd->vert = wd->vert + 1; 

wd->horz = wd->horz - 1; /* subtract out new line character 
*/ 

if (wd->horz > wd->maxhorz) wd->maxhorz = wd->horz; 
wd->horz = 0; 

WinSendMsg(sbh, SBM_SETSCROLLBAR, 

MPFROMSHORT(currenth), 

MPFR0M2SH0RT(1, wd->maxhorz)); 

WinSendMsg(sbh, SBM_SETTHUMBSIZE, 

MPFR0M2SH0RT(wd->colsperscreen, wd->maxhorz), 
MPFROMSHORT(0)); 


WinSendMsg(sbv, SBM_SETSCROLLBAR, 

MPFROMSHORT(currentv), 

MPFR0M2SH0RT(1, wd->vert)); 

WinSendMsg(sbv, SBM_SETTHUMBSIZE, 

MPFR0M2SHORT(wd->rows perscreen, wd->vert) , 
MPFROMSHORT(0)); 

1 


if (wd->event_fi1e != NULL) 

{ 

fputs(msg, wd->event_fi1e); 

WinlnvalidateRect(hwnd, NULL, FALSE); 
} 
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Besides setting the scroll bar range, you are also supposed to set the thumb 
(or slider) size by sending the scroll bar an SBM_THUMBSIZE message with 
mpl containing the size of the current screen in the first short, and the total 
number of columns or rows of data in the second. 

This creates the effect of the long slider position in the editor getting shorter 
and shorter as the number of lines in the file grows. 

The rowsperscreen and colsperscreen fields are part of the WINDOWDATA 
structure created in the last chapter. (See Listing 5-1.) 

Having set up the scroll bars with the proper range, we now must respond to 
them when they change. Any scroll bar can send either a WM_HSCROLL or a 
WM_VSCROLL. SHORT 1 in mpl contains the scroll bar ID, which is important 
only if you have more than one vertical or horizontal scroll bar. SHORT 1 in 
mp2 contains either zero or the new scroll bar position if the user has been 
dragging the scroll bar thumb. 

SHORT2 in mp2 may have any one of the values shown in Table 6-2. 

Just because the user clicks on the scroll bar doesn’t mean that the scroll bar 
is actually going to change. Think about it: How much should it change? How 
would it know? 

One might suspect that the scroll bar contains this information as part of its 
makeup, and we could set this through a WinSendMsg. But in fact it does 
not, and we must respond to the scroll bar’s messages by changing the scroll 
bar. 

case WMJ/SCROLL: 

wd = WinQueryWindowPtr(hwnd, 0); 
mr = WinSendMsg! 

WinWindowFromID! 

WinQueryWindow(hwnd, QW_PARENT), FID_VERTSCROLL), 

SBM_QUERYPOS, 0,0); 
vpos = SH0RT1FR0MMR(mr); 

switch!SH0RT2FR0MMP(mp2)) { 

case SB_LINEUP: 

vpos = vpos - 1; 
break; 

case SB_LINEDOWN: 
vpos = vpos + 1; 
break; 


case SB_PAGEUP: 



Part 1 From Square One (and Ground Zero!) 


Table 6-2 Values for SH0RT2 in mp2 

Scroll Bar Type 

Command 

Purpose 

Both 

SB_ENDSCROLL 

User has finished 

scrolling. If the user is dragging the 
thumb, SB_SL1 DERPOSITION is sent 
instead. 

Both 

SB_SL1 DERP0SIT10N 

User has stopped 

dragging the thumb. SH0RT1 of mp2 
contains the current thumb position. 

Both 

SB_SLIDERTRACK 

User is dragging the 

thumb. SH0RT1 of mp2 contains the 

current thumb position. 

Horizontal 

SB_LINELEFT 

User clicked on left arrow or pressed 
left cursor. 

Horizontal 

SB_LINER!GHT 

User clicked on right arrow or 
pressed right cursor. 

Horizontal 

SB_PAGELEFT 

User clicked to the left of the thumb. 

Horizontal 

SB_PAGERIG HT 

User clicked to the right of the thumb. 

Vertical 

SBJJNEDOWN 

User clicked on the down arrow or 
pressed the down cursor. 

Vertical 

SB_LINEUP 

User clicked on the up arrow or 
pressed the up cursor. 

Vertical 

SB_PAGEDOWN 

User clicked below the thumb or 
pressed Page Down. 

Vertical 

SB_PAGEUP 

User clicked above the thumb or 
pressed Page Up. 


vpos = vpos - wd->rowsperscreen; 
break; 


case SB_PAGEDOWN: 

vpos = vpos + wd->rowsperscreen; 

break; 

case SB_SLIDERPOSITION: 

vpos = SH0RT1FROMMP(mp2); 
break; 
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default: /* ignore other messages passed */ 
return 0; 


Before calculating the new thumb position, we must get the old thumb posi¬ 
tion from the scroll bar. The scroll bar returns its position in the first short 
of MRESULT, which forces us to declare an MRESULT variable (mr) and a sep¬ 
arate variable to hold the actual information we need (vpos). 

After calculating the new thumb position from vpos and the SBM_* com¬ 
mand, we must tell the scroll bar to change itself. 

WinSendMsg( 

WinWindowFromID( 

Wi nQueryWi ndow(hwnd, QW_PARENT), FID_VERTSCROLL), 

SBM_SETPOS , MP FROM SHORT (vpos ), Oh- 

After setting the scroll bar position, we must redraw and break out of the 
switch statement. 


WinlnvalidateRect(hwnd, NULLHANDLE, TRUE); 
break; 

Also note that the SB_SLIDERTRACK command is ignored completely and 
gets passed back with no action taken. In some cases it may be a bad idea to 
track with the slider, particularly if doing so will slow down the user input. 
Other times, refreshing the screen as the user drags the thumb will be vital. 
Because we’re reading sequentially from a text file each time, it’s probably 
not a good idea here, but you can un-comment out the code to try it on your 
system. 

Finally, we have to change the Paintlt method. Again we use WinQueryWin- 
dow, WinWindowFromID, and WinSendMsg. 

MRESULT Paintlt(HWND hwnd) 


/* 


H PS 

RECTL 

LONG 

FONTMETRICS 

FILE 

char 


hps ; 
rcl ; 

charHeight; 
fontMetrics ; 

*paint_fi1e; 

event_description[1000] ; 


new declarations */ 


SWP swp; 

int currentline, hpos, vpos; 

HWND frame; 

MRESULT mr; 
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PWINDOWDATA wd; 

wd = WinQueryWindowPtr(hwnd, 0); 

fclose(wd->event_fi1e);/* necessary for IBM CSET++ */ 

paint_file = fopen(wd->fi1ename, "r"); 

hps = WinBeginPaint(hwnd, NULLHANDLE, NULLHANDLE); 

WinQueryWindowRect(hwnd, &rcl ); 

WinFi11Rect(hps, &rcl , CLR_WHITE); 

GpiQuery FontMetrics(hps, sizeof(fontMetrics), &fontMetrics ); 

charHeight = fontMetrics.1MaxBaselineExt; 

if (paint_file!=NULL) { 

WinQueryWindowPos(hwnd, &swp); 
wd->rowsperscreen = swp.cy / charHeight; 
wd->colsperscreen = swp.cx / fontMetrics.1Emlnc; 

rcl .yBottom = rcl.yTop-charHeight; 

/* New Section for Chapter 6 */ 

frame = WinQueryWindow(hwnd, QW_PARENT); 

mr = WinSendMsg( 

WinWindowFromID(frame, FID_H0RZSCR0LL), 

SBM_QUERYPOS, 0,0); 
hpos = SHORTlFROMMR(mr); 
mr = WinSendMsg( 

WinWindowFromlD(frame, FID_VERTSCROLL), 
SBM_QUERYPOS, 0,0); 
vpos = SHORTlFROMMR(mr); 

current!ine = 0; 

/* end New Section for Chapter 6 */ 
do { 

currentline = currentline + 1; /*new*/ 

fgets(event_description, 1000, paint_fi1e); 

if (feof(paint_fi1e)) break; 

if (currentline<vpos) continue; /*new*/ 

if (hpos>strlen(event_description)) continue; /*new*/ 

WinDrawText(hps, strlen(event_description)-l, 

event_description, &rcl, 0, 0, DT_TEXTATTRS); 

rcl.yTop = rcl.yTop - charHeight; 

rcl.yBottom = rcl.yBottom - charHeight; 

} while (rcl.yBottom >= 0); 


fclose(paint_fi1e); 
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wd->event_fi1e = fopen(wd->fi1ename, "a"); 
WinEndPaint(hps ); 

return 0; 

} 


In this case, we use SBM.QUERYPOS in conjunction with WinSendMsg to 
ascertain the current location of the thumb in the scroll bars. Based on this 
information, we draw the window. 

This is also where we determine how many rows and columns we can get on 
the screen. We can determine the rows from the charHeight variable, which 
we calculated in the last chapter based on the FONTMETRICS structure’s 
IMaxBaselineExt field. Divide into the total window height by this value to 
find how many rows will fit. 

To calculate the number of columns across, we call upon another FONTMET¬ 
RICS field, lEmlnc, which represents the Em Increment for the font. Tradition¬ 
ally, the em dash (—) is the widest character in a font, and so by dividing the 
total width of the screen by that amount we get the minimum number of 
characters that will fit on screen. 


Timers 


We have one last, simple, but vitally important PM feature to look at. As men¬ 
tioned earlier, OS/2 supports multithreading but has only one message queue 
for all PM applications. As a result, one badly behaved PM application can 
prevent the user from interacting with all the other applications on the Desk¬ 
top (although running applications continue to run). 



Because of this, most PM applications set up two threads: one to handle user 
input and one for background processing tasks. However, you don’t have to 
get that fancy: By using system timers you can make your program appear to 
multitask without using separate threads. 

Threads are covered in Chapter 21. 

You need to know only two calls to use a system timer: WinStartTimer and 
WinStopTimer. 


General Form: ULONG WinStartTimer(HAB hab, HWND hwnd, ULONG id, 
ULONG delay); 

As Used: WinStartTimer(hab, hwnd, timer, 1000); 

General Form: BOOL WinStopTimer(HAB hab, HWND hwnd, ULONG id); 
As Used: WinStopTimer(hab, hwnd, timer); 
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WinStartTimer requires the anchor block and window handles, and also an ID 
number for the timer. The last parameter determines the intervals (in 
milliseconds) at which the timer will send your application WM JTIMER mes¬ 
sages. 




The fact that the interval is specified in milliseconds can give you an inflated 
idea of how fast you can receive these messages. In fact, specifying an inter¬ 
val of zero will result in the fastest stream of WMJTIMER messages possible 
on a PC, which they tell me is about 18 times a second. (Faster than / can 
count.) So, any interval less than fifty is pretty much the same as zero. 

Em also told that this 18/second pulse can be altered. 


Prior to Warp, no timer interval over 65,535 would work. OS/2 version 3.0, 
however, allows you to specify the full range of 32-bit integer values, which 
means you can set your timer to go off at the same time every day, or even 
every week or lunar month! 


Another thing to keep in mind is that OS/2 is, by nature, a relaxed system. 
That means you wouldn’t want to set your pacemaker using OS/2, because if 
it gets caught up in some intense drawing or other high-priority process, it’ll 
wait before issuing the WMJTIMER message. If two WMJTIMER messages get 
caught in the queue at once, OS/2 will combine them. 


You can ascertain how much time has passed between two timer events by 
querying the system clock. WinGetCurrentTime returns the milliseconds that 
have passed since you booted OS/2. 


General Form: ULONG WinGetCurrentTime(HAB hab); 
As Used: time = WinGetCurrentTime(HAB); 


The time rolls over every 48 days or so, since the timer is a 32-bit integer. 

In practice, responding to a WM_TIMER message is no different than 
responding to any other message, as this example from Events shows: 


WMJTIMER: 

Event("Tick\n"); 
break; 


Keep in mind, however, that if you’re using the timer to multitask, you’ll want 
to respond to the WMJTIMER message as quickly as possible. Using this 
approach, you still need to break your task up into small pieces that can be 
handled in an acceptable amount of time without tying up the PM message 
queue. 
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The “official" maximum amount of time allowed for handling messages in the 
PM message queue is around l/10th of a second. If processing takes longer 
than that, the user will notice a drag on the system. 


Conclusion 

Input is, of course, important in every programming system and OS/2 is no 
exception. Direct interaction with keystrokes and mouse clicks, however, is 
less desirable than interacting with user commands (such as “open a file" or 
“click on a button”). 

The next part of this book covers setting up commands for the user to 
generate. 




The 5th Wave 















In This Part .. 


1# ou are introduced to the concept of resources, and 
Jr* you learn how to build OS/2 menus, how to draw 
basic images on screen, how to use two of the standard 
OS/2 dialogs, and how to create dialogs of your own. 
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What's on the Menu? 

!n This Chapter 

► Resource file basics 

► Menu construction and use 

► Mapping window points 

► Creating pop-up menus 

► Setting menu items at run-time 

► Sending messages to windows 


••••••••••••••••• 


lyf ou may not have noticed, but cutting-edge GUI applications are reducing 
the importance of the menu bar, and of menus in general. In fact, some 
design philosophies suggest that it would be best to entirely eliminate menus 
from programs. (They would be replaced by context-sensitive toolbars in 
many cases.) 



Although I’ve been a fan of menu bars and submenus in the past, I’m begin¬ 
ning to agree with this thinking, since after you’ve selected OPTIONS I ENVI¬ 
RONMENT I PROGRAMS I MACROS I RECORD a dozen times, menus can start to 
wear thin. And if you’re looking for a specific feature, the Help system invari¬ 
ably tells you what a feature means, but not where to find it in the menu 
system! 


Unfortunately, one common solution is to pile dialogs on top of dialogs, 
which still makes menus look pretty good. 

At this point in the software business, most applications still use menu bars, 
and even WPS applications are more or less required to have a context menu 
appear when the user clicks the secondary mouse button over the menu bar. 

We’ll look at constructing menus in OS/2 in this chapter, as well has how to 
field the commands that menus generate. We’ll also use this time to get a feel 
for what resource files are and how they are used. 



100 Part SS Resources and Dialogs—Getting in Touch with Your OS 


The Resource File 

If you opened a text file that contained this information, what would you 
think it was? 

//include "menu.h" 

MENU MENUPROGRAMID 
BEGIN 

MENU ITEM "@", MID_AB0UT, , 

SUBMENU "-File", MID_FILE, , 

BEGIN 

MENUITEM "~0pen\tCtrl +0", 

SUBMENU "-Settings\tShift+Fl1 
BEGIN 

MENUITEM "Stuff", 

MENUITEM "More Stuff", 

END 

MENUITEM SEPARATOR 
MENUITEM "Last Item", 

END 
END 

You’d probably think it was a menu description, maybe for a language like 
dBASE or something. Well, it is a menu description—in OS/2’s resource file 
language, which we can gratefully refer to as “the resource language.” (No 
acronyms! Hooray!) 

The resource language allows you to easily describe instances of window 
classes that you would like to use in your application. The preceding example 
describes an instance of the menu class. 

Without resource files, you would have to construct your menus using API 
call after API call, a tiring and error-prone approach that also takes up code 
space unnecessarily. 

After creating a resource file, you compile it using a resource compiler (sup¬ 
plied with most compilers and with the IBM toolkit) and then link it into the 
client application’s executable file. 

IBM C/Set++, Borland C++ for OS/2, and Watcom C++ each provide Integrated 
Development Environments (IDEs) which recognize the .RC extension as a 
resource file and automatically compile and link such files into your applica¬ 
tion’s executable. 



MID_FILEOPEN, 
MID_SETTINGS, , 

MID_STUFF, 
MID._M0RESTUFF, , 


MID_END1, 



_ tip**. 
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IBM’s WorkFrame/2 is an IDE that works with most OS/2 language compil¬ 
ers, and will ease the task of building executables with built-in resources. 

You can compile your own resources by using the resource compiler sup¬ 
plied with the Developer’s Toolkit (RC.EXE) and linking them into your code 
yourself. You can compile a resource and bind it into an .EXE by typing: 

rc MyRes.RC MyProgram.EXE 

from the OS/2 command line in the directory containing both MyRes.RC and 
MyProgram.EXE. 

If you’re going to be recompiling the .EXE a lot but not changing the resource, 
you may want to compile the resource first, and then bind that into the .EXE. 

rc -r MyRes.RC 
rc MyRes.Res MyProgram.EXE 

This is faster than recompiling the resource every time you recompile the 
.EXE. 

Besides menus, resource files can contain descriptions of accelerator (or hot¬ 
key) tables, extended attributes for files (such as the application’s icon), win¬ 
dows, and many other items. 



Describing a Menu 



You start a menu description with the resource keyword MENU. The 
resource language is not case sensitive, but by custom keywords appear 
entirely in uppercase letters in resource files. The menu is followed by a 
numeric identification value. 

This ID can be used in your application to get a handle to the menu via 
WinWindowFromID. 



After the ID you can also specify load options and memory options. The load 
options are PRELOAD and LOADONCALL. PRELOAD means that the resource 
is loaded immediately when the application runs. LOADONCALL, on the other 
hand, means that the resource will not be loaded until the application uses it. 


The memory options determine how freely OS/2 is allowed to move 
resources around in memory. The defaults for these options are different for 
different resource types. For our purposes, the defaults are adequate. 
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It’s bad practice to use numeric literals to identify your resources, which is 
why the resource file shown previously began with: 

ffvncl tide "menu.h" 

Resource files understand not only include directives, but define directives 
as well This allows us to use the file containing the menu IDs in both the 
resource file and the program file. 


^define MENUPROGRAMID 1000 


#define MID_AB0UT 2000 
^define MID_FILE 3000 
^define MID_FILEOPEN 3001 
#define MID_SETTINGS 3100 
^define MID_STUFF 3101 
^define MID_MORESTUFF 3102 
#define MID_.END1 3002 


Resource files allow two types of statements: single-line and multiline. Menus 
are multiline statements, so the MENU line is followed by a series of other 
lines encompassed by a BEGIN and an END. 

MENU MENUPROGRAMID 
BEGIN 

END 


Menus themselves accept single-line or multiline statements. The single-line 
menu statement is MENUITEM. 


MENU ITEM , MI D_AB0UT , 

MENUITEM "~Open\tCtrl+0", 


MID_FILEOPEN, 


MENUITEM "Stuff", MID_STUFF, 

MENUITEM "More Stuff", MID_M0RESTUFF, , 


MENUITEM SEPARATOR 

MENUITEM "End of columnl", MID_END1, 


MENUITEM, not surprisingly, describes a menu item. More explicitly, it 
describes an item that does not expand further into a submenu. MENUITEM 
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can be followed by the keyword SEPARATOR, which creates a horizontal 
dividing line used to group items aesthetically. 

If not defined as a separator, a menu item is followed first by a descriptive 
string (enclosed in quotes) that will appear in the menu, then by a comma 
and the command that selecting that item will activate. 

MENU ITEM "Stuff", MID_STUFF, 


The string can include a tilde prior to the letter that the user can press to 
select the item from the menu. It can also include a “Yt”, which the resource 
compiler interprets as a tab. This is usually followed by a hot-key descrip¬ 
tion, as in “\tCtrl+0” in the preceding example. 



Hot-keys and text descriptions have no actual connection, unfortunately. In 
other words, just because we have “~0pen\tCtrl+0” here, that doesn’t mean 
that Ctrl+O will generate the FILE_OPEN command. 

To connect menu commands and hot-keys we need an accelerator table, cov¬ 
ered later on in this chapter. 


The string may also include a “\a” which causes the resource compiler to 
flush right any text after the “\a”. 

Two other options can be specified for menu items, as you probably guessed 
from the two extra commas following each item. Option number three speci¬ 
fies the menu item style , which can be MIS_TEXT to indicate that the item is a 
text string (the default), or MIS_BITMAP to indicate that the menu item is a 
bitmap. There are some other menu style possibilities as well, and we will 
look at these later. 



You don’t need to trail the menu items with commas if you aren’t specifying 
either of these extra options. I sometimes add them as placeholders, so that 1 
remember that the options can be specified, and that there are two different 
sets. (The importance of this will become apparent in a page or two.) 


The last option can be any combination of several styles, as shown in 
Table 7-1. As you might imagine, these are options that you will often want to 
set dynamically. We’ll look at how to do that later on in this chapter. In par¬ 
ticular, MIA_HILITED simply indicates whether an item appears selected to 
begin with. If it is and the user selects it again and then moves off it, the item 
will be de-highlighted. In other words, MIAJHILITED describes a transient 
state, not a permanent one. 


To use the MIA_* attributes in your resource files you must include the 
0S2.H header file in your resource file. Here’s what the resource file looks 
like with the M1A_* options set on the menu items. 
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Table 7-1 Menu Item Attributes 

Attribute Name 

Effect 

MIA_CHECKED 

Check mark appears to the left of the item. 

MIA_DISABLED 

Item is unselectable and grayed out. 

MIA_FRAMED 

Item is drawn with frame around it. 

MIA_HILITED 

Item appears to be selected. 

MIAJMODISMISS 

Menu(s) remains even after the item is selected. 


//include <os2.h> 

//include "menu.h" 

DEFAULTICON <testico . ico> 


MENU MENUPROGRAMID 
BEGIN 

MENUITEM MID_AB0UT , 

SUBMENU "-File", MID_FILE , 

BEGIN 

MENUITEM "~0pen\tCtrl+0", MID_FILEOPEN, ,MIA_DISABLED 

SUBMENU "-Settings\tShift+F10",MID_SETTINGS, , 

BEGIN 

MENUITEM "Stuff",MID_STUFF,,MIA_CHECKED|MIA_N0DISMISS 
MENUITEM "More Stuff", MID_MORESTUFF, ,MIA_HI LI TED 
END 

MENUITEM SEPARATOR 

MENUITEM "End of columnl",MID_END1„ ,MIA_FRAMED 
END 
END 



The resource language bears a resemblance to C, as is apparent from this 
sample. Besides the include directives, menu options are combined using the 
I operator. 



Notice that the menu item style, even if blank, must have the comma place¬ 
holder to distinguish it from the menu item attributes. In other words, 

MENUITEM "~0pen\tCtrl +0", MID_FILEOPEN, ,MIA_DISAB LED 
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is correct, but 

MENU ITEM "~Open\tCtrl+0", MID_FILEOPEN, MIA_DISABLED 

is not. That’s why I sometimes leave in both commas, even if I don’t set either 
of the options. If I come back later to add an attribute but not a style, I 
remember that the other comma is necessary. 

Incorporating a Menu into \lour 
Application 

Incorporating the menu from your resource file into your OS/2 application is 
a piece of cake when you use WinCreateStdWindow. Simply include the same 
header file that you used to build the resource file (MENU.H, in this example) 
and specify the menu ID as the second to last parameter in WinCreateStd¬ 
Window. 

hwndFrame = WinCreateStdWindow(HWND_DESKT0P, WS_VISIBLE, 

&f1FrameOpts, szClassName, 
szWindowTitle, 0L, 0, 

MENUPROGRAMID, 

&hwndClient); 

Additionally, the frame options should indicate that there is a menu. Remove 
the “~FCF_MENU” from the declaration of flFrameOpts: 

ULONG flFrameOpts = FCF_STANDARD & ~FCF_IC0N & 

~FCF_ACCELTABLE; 


That’s all it takes. 



You must compile the resource (.RC) file and link the file into your compiled 
program in order for this to work. As mentioned previously, most IDEs will 
do this for you, but if the sample doesn’t work, then you may have to do this 
by hand. Check your manuals. 


Although it is possible to use a resource module other than the one linked 
into a program’s .EXE file, we won’t be doing that in this book. The sample 
program is essentially the basic application framework first described in 
Chapter 3. 


//define INCL_GPI 
//define INCL_WIN 
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//include <os2.h> 

//include <string.h> 

//include <menu.h> 

MRESULT EXPENTRY ClientWndProc(HWND, ULONG, MPARAM, MPARAM); 

int main (void) 

{ 

HAB hab; /* anchor block handle */ 

HMQ hmq; /* message queue handle */ 

HWND hwndFrame, hwndClient; /* handles to windows */ 

QMSG qmsg; /* message */ 

char szClassName[] = "Resource Test"; 
char szWindowTitle[] = "Menus, Etc."; 

ULONG f1FrameOpts = FCF_STANDARD & ~FCF_IC0N & 
~FCF_ACCELTABLE; 


hab = WinInitia 1iz e(0); 

hmq = WinCreateMsgQueue(hab , 0); 

WinRegisterClass(hab, szClassName, ClientWndProc, 

CS_SIZEREDRAW, 0); 

hwndFrame - WinCreateStdWindow(HWND_DESKTOP, WS_VISIBLE, 

&flFrameOpts, szClassName, 
szWindowTitle, 0L, 0, 
MENUPROGRAMID, 

&hwndClient); 

while (WinGetMsg(hab, &qmsg, 0, 0, 0)) 

WinDispatchMsg(hab, &qmsg); 

WinDestroyWindow(hwndFrame); 

WinDestroyMsgQueue(hmq); 

WinTerminate(hab); 

return 0; 


MRESULT EXPENTRY ClientWndProc(HWND hwnd, ULONG msg, MPARAM mpl, 
MPARAM mp2) 

{ 

HPS hps ; 

RECTL rcl; 

/*event handler*/ 
switch(msg) { 
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case WM_PAINT: 

hps = WinBeginPaint(hwnd, NULLHANDLE, NULLHANDLE); 

WinQueryWindowRect(hwnd, &rcl); 

WinFi11Rect(hps, &rcl , CLR_WHITE); 

WinEndPaint(hps); 
return 0; 

} 

/*end event handlers */ 

return WinDefWindowProc(hwnd, msg, mpl, mp2); 

} 

What you should do now is use this program, which I’ll refer to as Menu, to 
experiment with menus. This will give you a good feel for how you want to 
space items, how you want to number the menu IDs, and so on. 

Some of the preceding listings are awkwardly spaced because 1 had to make 
them fit on the pages of this book. In general, I believe it’s better to spread 
things out so that they’re in neat columns. 

In a header file, I also tend to widely space (numerically speaking) my menu 
IDs from one level to the next. I number the main menus in 1000s, submenus 
in 100s, and sub-submenus in 10s. I number menu items sequentially. 

This scheme makes it possible to pull down a menu from the menu bar, open 
a submenu, and then open one submenu after that. This is as deep a menu 
structure as I would ever want to use, so I find this a good guideline. Follow 
your own preference. 


Pop-up Goes the Menu 

Key to a WPS application is the context menu. When the user clicks the sec¬ 
ondary mouse button over an object, a pop-up menu appears. A true WPS 
application does this by overriding the WPS method that creates the context 
menu (as covered in Chapter 24), but it’s a good idea in general to know how 
to pop up a menu, and it allows us to examine some other PM features in 
detail. 

The beauty of the resource file is that we can use the same menu for the pop¬ 
up menu that we’ve been using for the menu bar! 

The resource file contains a description of the menu from which PM creates 
an actual object. So any object described in a resource file can be used many 
times within the same program. 
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We could, in fact, reuse the same menu by using WinWindowFromID to get its 
handle, but as you don’t typically pop up the main menu, I’ve pretended that 
this is a different menu and used WinLoadMenu to get a handle to the menu. 



General Form: HWND WinLoadMenu(HWND hwnd, HMODULE resource, LONG ID); 
As Used: hwndPop = WinLoadMenu(hwnd , 0, MENUPROGRAM ID); 

If you want to destroy a menu, you can do so with WinDestroyWindow, as 
shown in the next listing. 


The second parameter could refer to a resource module other than the one 
integrated with the .EXE, as mentioned in the previous section, and the third 
parameter can be any ID that points to a valid menu. 


Let’s look at the code to create a pop-up menu. The code that follows shows 
only ClientWndProc. Nothing in the main function has changed. 


MRESULT EXPENTRY ClientWndProc(HWND hwnd, ULONG msg, MPARAM mpl, 
MPARAM mp2) 


HPS hps; 
RECTL rcl ; 
POINTL mouse; 


static HWND hwndPop; 

/*event handler*/ 
switch(msg) { 

case WM_CREATE: 

hwndPop = WinLoadMenu(hwnd, 0, MENUPROGRAM ID); 
return 0; 


case WM_DESTROY: 

WinDestroyWindow(hwndPop); 
return 0; 


case WM_PAINT: 

hps = WinBeginPaint(hwnd, NULLHANDLE, NULLHANDLE); 
WinQueryWindowRect(hwnd, &rcl ); 

WinFi11Rect(hps, &rcl , CLR_WHITE); 

WinEndPaint(hps ); 
return 0; 



Chapter 7 What's on the Menu 


case WM_CONTEXTMENU: 
if SH0RT2FR0MMP(mp2) 

WinQueryPointerPos(HWND_DESKTOP, &mouse); 
el se { 

mouse.x = SH0RT1FROMMP(mpl) ; 
mouse.y = SH0RT2FR0MMP(mpl); 

WinMapWindowPoints(hwnd, HWND_DESKTOP, &mouse, 1); 

} 

WinPopupMenu(HWND_DESKTOP, hwnd, hwndPop, mouse.x, mouse.y, 

0,PU_HCONSTRAIN | PU_VCONSTRAIN | 

PU_M0USEBUTT0N1 | PU_M0USEBUTT0N2 | 
PILKEYBOARD) ; 

return 0; 

} 

/*end event handlers */ 

return WinDefWindowProc(hwnd, msg, mpl, mp2); 

} 



Although I usually prefer to use window words to store a pointer to all data 
pertinent to any given window instance (as explained in Chapter 5), for sim¬ 
plicity’s sake I’ve declared a static local pointer to hold the pop-up menu. 

In this case, the static pointer is okay, because it’s never going to change, 
regardless of how or when the window procedure is called. 

WM_CONTEXTMENU can be created either by clicking the secondary mouse 
button on an object or by pressing Shift+FlO. If the user presses Shift+FlO, 
the WM_CONTEXTMENU contains no information as to where the mouse is. 


In a real application you would have an idea where the user’s attention was 
and you would pop the menu up near where you thought the user was look¬ 
ing—or you would cheat and query the mouse pointer location and pop the 
menu up near the mouse pointer anyway. (WPS does this sometimes, believe 
it or not! Just press Shift+FlO when the Task List is active to see.) 


Mapping Window points 

For this example, let’s cheat by using the WinQueryPointerPos function. We 
can learn some interesting things about menus by using the current pointer 
location as a focal point, as you’ll see. 

General Form: BOOL WinQueryPointerPos(HWND hwnd, PPOINTL p); 

As Used: WinQueryPointerPos(HWND_DESKTOP, &mouse); 
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The first parameter is always the Desktop handle and the second parameter 
contains the location of the pointer at the time the WM_CONTEXT message 
occurred. 

Now, this same code could have been used whether WM_CONTEXT was gen¬ 
erated by the mouse or the keyboard, but I want to introduce you to WinMap- 
WindowPoints. WinMapWindowPoints converts coordinates from one 
window to another. 

General Form: BOOL WinMapWindowPoints(hwnd from, hwnd to, PPOINTL 
ppl, LONG count) 

As Used: WinMapWindowPoints(hwnd, HWND_DESKTOP, &mouse, 1); 

Every window has its own (0,0) position, located in its bottom left corner. 

The mouse messages received by a window contain the coordinates of the 
mouse relative to that window. Child controls express their locations in the 
coordinates of their parents. (This was covered in Chapter 2.) 

The first two parameters indicate: 

^ The window in whose coordinate system the points are currently based. 

v* The window whose coordinate system you would like to have them 
translated to. 

The third parameter can point to an array of PPOINTLs. You tell WinMapWin¬ 
dowPoints how many points you want translated by specifying a number in 
the fourth parameter. 

So why are we mapping these coordinates? 

Menus are usually owned by your client window, but have the Desktop as 
their parent. This is so the menu can appear unclipped regardless of the 
state of its owning window. 

Owned controls send commands to their owners but are not clipped by their 
owner’s boundaries. Child controls are clipped by their parents, as described 
in Chapter 2. 

To understand what I’m getting at, run this program and shrink it down as 
small as you can without minimizing it. Now right-click in the lower right- 
hand corner of the client window—not on the frame, because you’re not try¬ 
ing to resize the window; you’re just interested in bringing up the context 
menu. 
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Where does the menu appear? Figure 7-1 shows you. Our example menu 
probably could fit into that reduced-size window, but a larger menu often 
won’t. Obviously, it’s important that entire menus appear. 


Figure 7-1: 
The menu 
appears 
outside the 
window that 
creates it. 



In fact, because we’re responding to Shift+FlO, you can position the mouse 
entirely off the window and on the Desktop, then press Shift+FlO and 
watch as the menu pops up over wherever the mouse is. (This wouldn’t 
necessarily be a good design choice, however.) 


WinPopupMenu 

Nothing remains, then, but for us to look at WinPopupMenu. WinPopup¬ 
Menu allows you to set a number of options that determine where the 
menu pops up and how it behaves on arrival. 

General Form: BOOL Wi nPopupMenu( HWND parent, HWND owner, HWND 
menu, LONG x, LONG y, LONG ItemID, ULONG options) 

As Used: WinPopupMenu(HWND_DESKTOP, hwnd, hwndPop, 

mouse.x, mouse.y, 0, 

PU_HCONSTRAIN | PU__VCONSTRAIN | 
PU_M0USEBUTT0N1 | PU_M0USEBUTT0N2 | 
PU_KEYBOARD); 

Although this is a rather involved call, it isn’t hard to understand. The first 
three parameters indicate the menu’s parent (boundaries that the menu 
will be clipped in, usually HWND_DESKTOP), the menu’s owner (the client 
window, usually the hwnd that received the message), and the menu itself. 

The simplest way to position the pop-up menu is to use the next two para¬ 
meters to specify the location (x, y). 

The last parameter determines a number of things about the pop-up menu. 
Although these are specified as bits in the same field, only certain combi¬ 
nations are really related. 
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Normally the menu appears with its lower-left corner at the (x,y) you specify. 
If you set PU_POSITIONONITEM, however, the menu item matching ItemID 
will appear at that location instead. This is easier to see than to read. Replace 
the code in Menu with this: 


WinPopupMenu(HWND_DESKTOP, hwnd, hwndPop, mouse.x, mouse.y, 

MID_AB0UT, PU_P0SITIONONITEM | PU_HC0NSTRAIN | 
PU_VCONSTRAIN, | PU_M0USEBUTT0N1 | 

PU_M0USEBUTT0N2 | PU_KEYBOARD); 

The pop-up menu appears with MID_ABOUT (the @ sign) directly under the 
mouse pointer. This works only with top-level menu items. If you specified 
MID_STUFF, for example, the menu wouldn’t pop up at all. 

To ensure that the entire width of the menu appears on screen, you use 
PU_HCONSTRAIN. To ensure that the entire length of the menu appears on 
screen, use PU_VCONSTRAIN. You can observe the effects of these parame¬ 
ters in the menu program by positioning the mouse in the bottom right-hand 
corner of the screen and pressing Shift+FlO. The x and y parameters are not 
absolute if these items are selected—fitting the entire menu on screen takes 
priority. 

One formerly common approach to selecting menu items was to click and 
hold to bring up the menu, then drag the mouse over the menu and release 
the mouse button only when you made your choice. 

That doesn’t work with context menus because they are called up by clicking 
the secondary mouse button. If you put this menu up in response to a BUT- 
TONxDOWN message, however, you might want to enable this feature. 

To do so you would set the PU_MOUSEBUTTONlDOWN, 
PU_MOUSEBUTTON2DOWN, or PU_MOUSEBUTTON3DOWN options. The 
default is PU_NONE, meaning you can’t drag to select an item. 

You can force a particular menu item to be selected when the menu is first 
popped up, however, via PU.SELECTITEM. This, too, like PUJPOSITIONON- 
ITEM, uses the ID parameter. Unlike that option, however, PU_SELECTITEM 
can be used with non-top-level items. Try the following: 



WinPopupMenu(HWND_DESKTOP, hwnd, hwndPop, mouse.x, mouse.y, 

MID_STUFF, | PILHCONSTRAIN | PILVCONSTRAIN | 

PU_SELECTITEM | PU_M0USEBUTT0N1 
| PILM0USEBUTT0N2 | PU_KEYBOARD); 

If you haven’t specified PU_POSITION or PU_SELECT1TEM, the ItemID para¬ 
meter should be blank. 
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Finally you must allow the pop-up menu items to be selected through some 
input device. The PUJKEYBOARD, PU_MOUSEBUTTONl, PUJMOUSEBUT- 
TON2, and PU_MOUSEBUTTON3 options will set the items to be selectable by 
those devices. 


Command Performances 

Having menus is swell, but also meaningless unless your program actually 
does something with the commands that the menus generate. 

Menu items usually generate WM_COMMAND messages, but you can instead 
make them generate either WM_HELP messages or WM_SYSCOMMAND mes¬ 
sages. Look back at the resource language’s MENUITEM keyword: 

MENUITEM "Last Item",MID_END1, ,MIA_FRAMED 

If you wanted to make “Last Item” generate a WM_HELP command, you would 
add MIS_HELP after the second comma: 

MENUITEM "Last Item", MID_END1, MIS_HELP, MIA_FRAMED 

If you wanted to make “Last Item” generate a WM_SYSCOMMAND command, 
you would add MIS_SYSCOMMAND instead: 

MENUITEM "Last Item", MID_END1, MIS_SYSCOMMAND, MIA_FRAMED 

Regardless of the message type generated, your program acts on the menu 
item’s command (in this example, MID_END1). There’s nothing really exotic 
about this—it’s more or less what we covered in the last two chapters on 
input. Within your window procedure you would have a case statement like 
this: 

case WM_COMMAND: 
switch(SH0RT1FROMMP(mpl)) { 
case CMD_SOMECOMMAND: 

/* actual code to handle CMD_SOMECOMMAND here*/ 


Dynamically Setting Menu Attributes 

We’ll experiment with menu commands by using them to set the state of 
menu items. This way not only can you become confident about reacting to 
menu-generated commands, you can also become more confident about 
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sending messages to other windows, which was something we touched on in 
the last chapter (with scroll bars). 

Let’s start by creating a new resource file, with a new menu. This one will be 
designed to create effects on other menu items. 

^include <os2.h> 

#include "menu2.h" 

MENU MENU2PR0GRAMID 
BEGIN 

SUBMENU "-Commands",MID_COMMANDS,, 

BEGIN 

-Command",CMD_COMMAND,, 

"C~heck\tCtrl+F10",CMD_CHECK,, 

-Stick",CMD_STICK,,MIA_N0DISMISS 
-Disable\tCtrl+D",CMD_DISABLE,, 

-Enable\tCtrl+E",CMD_ENABLE,, 

-Variable",CMD_VARIABLE,, 


MENUITEM 

MENUITEM 

MENUITEM 

MENUITEM 

MENUITEM 

MENUITEM 

END 


END 

This program and its header file reflect a practice that I find useful: Prefix the 
names of menus with MID_ and the names of commands with CMD_. This 
practice minimizes any risk of me trying to act on a command that isn’t a 
command but a menu ID. 

#define MENU2PR0GRAMID 1000 


#define MID_COMMANDS 


2000 


#def ine 
#define 
#define 
#def ine 
#def ine 
#define 


CMD_COMMAND 

CMD_CHECK 

CMD_STICK 

CMD_DISABLE 

CMD_ENABLE 

CMD_VARIABLE 


2001 

2002 

2003 

2004 

2005 

2006 


Now we need a program to act on these commands. Look most closely at the 
WinSendMsg functions. (Only ClientWndProc changed from the last program, 
so I haven’t included the main function or defines.) 


MRESULT EXPENTRY ClientWndProc(HWND hwnd, ULONG msg, MPARAM mpl, 
MPARAM mp2) 


HPS hps; 
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RECTL rcl ; 

static char text[] = "Enough space to accomodate new messages. 
ULONG displayOpts = DT_TEXTATTRS | DT_CENTER | DT_VCENTER; 
HWND menu, frame; 

BOOL newstatus; 

/*event handler*/ 
switch(msg) { 
case WM_PAINT: 

hps = WinBeginPaint(hwnd, NULLHANDLE, NULLHANDLE); 

Wi nQueryWindowRect(hwnd, &rcl ); 

WinFi11Rect(hps, &rcl , CLR_BACKGROUND); 

GpiSetBackMix(hps , BM_OVERPAINT); 

WinDrawTextChps, -1, text, &rcl, 0,0, displayOpts); 

WinEndPaint(hps); 

return 0; 

case WM_COMMAND: 

frame = WinQueryWindow(hwnd, QW_PARENT); 
menu = WinWi ndowFromlD(frame, FID_MENU); 

switch(SH0RT1FROMMP(mpl)) { 

case CMD_COMMAND: 
strcpy(text, "Command!"); 
break; 

case CMD_CHECK: 

if (WinSendMsg(menu, MM_QUERYITEMATTR, 

MPFR0M2SHORT(CMD_CHECK, TRUE), 

MPFR0M2SHORT(MIA_CHECKED, 0))) 

{ 

strcpy(text, "Unchecked!"); 
newstatus = 0; 

} 

el se { 

strcpy(text, "Checked!"); 
newstatus = MIA_CHECKED; 


WinSendMsg(menu, MM_SETITEMATTR, 
MPFR0M2SH0RT(CMD_CHECK, TRUE), 

MPFR0M2SHORT(MIA_CHECKED, newstatus)) ; 
break; 
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case CMD_STICK: 
strcpy(text, "Sticky!"); 
break; 

case CMD_DISABLE: 

strcpy(text, "Disabling menu item."); 

WinSendMsg(menu, MM_SETITEMATTR, 

MPFR0M2SH0RT(CMD_VARIABLE, TRUE), 

MPFR0M2SH0RT(MIA_DISABLED, MIA_DISABLED)); 
break; 

case CMD_ENABLE: 

strcpy(text, "Enabling menu item."); 

WinSendMsg(menu, MM_SETITEMATTR, 

MPFR0M2SHORT(CMD_VARIABLE, TRUE), 

MPFR0M2SH0RT(MIA_DI SAB L ED, 0)); 
break; 

case CMD_VARIABLE: 

strcpy(text, "Variable: Item sometimes disabled."); 
break; 

} 


WinlnvalidateRect(hwnd, NULL, FALSE); 
break; 

} 

/*end event handlers */ 


return WinDefWindowProc(hwnd, msg, mpl, mp2); 
} 


The two messages sent to the menu in this program are MM_QUERYITEM- 
ATTR and MM_SETITEMATTR. They’re very similar: mpl is the menu item’s 
ID, and indicates whether you want to search submenus for the ID if the item 
is not in the top-level menu. (This should usually indicate “yes.”) 

In MM_SETITEMATTR, mp2 contains two bit masks, both consisting of MIA_ 
flags. The first bit mask indicates which flags you want to affect; the second 
bit mask indicates how you want to affect them. MM_QUERYITEMATTR uses 
only the first bit mask, and returns the bits that the queried item has set. 

The simplest use is to enable and disable the CMD_VARIABLE menu item. 
This requires no querying, as shown: 

case CMD_DISABLE: 

strcpy(text, "Disabling menu item."); 



Chapter 7 What's on the Menu 117 


WinSendMsg(menu, MM_SETITEMATTR, 

MPFR0M2SH0RT(CMD_VARIABLE, TRUE), 
MPFR0M2SH0RT(MIA_DISABLED, MIA_DISABLED)); 
break; 


Here we’re only interested in the MIA_DISABLED option, and we want it to be 
set on so we indicate that in both parameters. Later, in response to 
CMD_ENABLE, we want that bit to be cleared: 

case CMD_ENABLE: 

strcpy(text, "Enabling menu item."); 

WinSendMsg(menu, MM_SETITEMATTR, 

MPFR0M2SHORT(CMD_VARIABLE, TRUE), 

MPFR0M2SHORT(MIA_DISABLED, 0)); 
break; 



Strictly speaking—from the standpoint of designing a user interface—after 
disabling the CMD_VARIABLE menu item, the CMD_DISABLE item should dis¬ 
able itself and enable CMD_ENABLE. When CMD_ENABLE enables CMD_VARI¬ 
ABLE, it should disable itself and enable CMD_DISABLE. That way the user 
cannot select a menu item that has no effect. 


More complex logic can be found in response to CMD_CHECK. The code first 
asks the menu item whether it is checked, then either checks it or unchecks 
it appropriately: 

if (Wi nSendMsg(menu, MM_QUERYITEMATTR, 

MPFR0M2SH0RT(CMD_CHECK, TRUE), 

MPFR0M2SHORT(MIA_CHECKED, 0))) 

Here, if the CMD_CHECK menu item is checked, WinSendMsg returns a bit 
mask with that bit set. This allows us to prepare a mask: 


strcpy(text, "Unchecked!"); 
newstatus = 0; 

} 

el se { 

strcpy(text, "Checked!"); 
newstatus = MIA_CHECKED; 


and send that mask to the menu item: 

WinSendMsg(menu, MM_SETITEMATTR, 

MPFR0M2SH0RT(CMD_CHECK, TRUE), 
MPFR0M2SH0RT(MIA_CHECKED, newstatus)); 
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This interaction between menus and your client window is more important 
than it may seem at first. Invoking WinSendMsg and responding to the results 
is the process you’ll use to interact with all other windows, including control 
windows such as radio buttons and list boxes. 


You’ll use this technique a lot in chapters 11 through 17. 


Bitmap menu items 

In these pages we’ve covered menus and options for menus, and we’ve seen 
that one option for a menu item is to be a bitmap instead of a text string. 

I have mixed feelings about using bitmaps in menus because I find text easier 
to understand than pictures. I’m probably ultra conservative, but I find it 
somewhat disturbing to pull down a menu and see a lot of tiny pictures. Kind 
of like looking at a neon-colored tuxedo! 

But enough of my hang-ups: Resource files for describing bitmap menus are 
not much different from regular resource files. The string portion of the 
description contains the identifier of the bitmap to be used, and the 
MIS_BITMAP style must be set. 

You can test this easily by copying over the following bitmaps from 
\0S2\BITMAPS to your source directory: BLOCKS.BMP, BOX.BMP, 
WEBB.BMP, ZIGZAG.BMP, and WAVE.BMP. Change the resource file to: 

#include <os2.h> 

#iinclude "menu2.h" 

BITMAP 1 box.bmp 
BITMAP 2 blocks.bmp 
BITMAP 3 zigzag.bmp 
BITMAP 4 webb.bmp 
BITMAP 5 wave.bmp 

MENU MENU2PR0GRAMID 
BEGIN 

SUBMENU "-Commands",MID_COMMANDS,, 

BEGIN 

MENU ITEM "-Command",CMD_COMMAND,, 

MENUITEM "C~heck\tCtrl+F10",CMD_CHECK,, 

MENUITEM "-Stick",CMD_STICK,,MIA_N0DISMISS 
MENUITEM "~Disable\tCtrl+D",CMD_DISABLE,, 

MENUITEM "-Enable\tCtrl +E",CMD_ENABLE,, 

MENUITEM "-Variable",CMD_VARIABLE,. 
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SUBMENU "#1",MID_GRAPHICS,MIS_BITMAP, 
BEGIN 

MENUITEM "#2",CMD_BLOCKS,MIS_BITMAP, 
MENUITEM ”#3",CMD_ZIGZAG,MIS_BITMAP, 
MENUITEM "#4",CMD_WEBB,MIS_BITMAP, 
MENUITEM "#5",CMD_WAVE,MIS_BITMAP, 
END 
END 
END 


Bitmaps, as you can see, are identified in a resource file by the keyword 
BITMAP, followed by a resource number and the bitmap’s filename. 



To specify that a menu item should be a bitmap, put the resource number in 
quotes preceded by a # sign and specify the style as M1S_BITMAP. 

In order to make this example work, you must define MID_GRAPHICS, 
CMD_BLOCKS, and so forth in MENU2.H. 


Hat-Keys 

Observe from the MENU2 program that even though Ctrl+C and Ctrl+D were 
specified as hot-keys in the resource file, those keys don’t actually do any- 
thing in the program. 

Hot-keys (sometimes called accelerator keys ) are described in a resource file, 
too, in what is known as an accelerator table. (The name “accelerator key” is 
brought to you, no doubt, by the same people who call a menu bar an “action 
bar.”) 

Accelerator tables are straightforward: 


ACCELTABLE 

BEGIN 

VK_F10, 
"d", 

" e", 

" v", 

END 


MENU2PR0GRAMID 


CMD_CHECK, 
CMD_DISABLE, 
CMD_ENABLE, 
CMD_VARIABLE 


VIRTUALKEY, 

CONTROL 

CONTROL 

CHAR 


CONTROL 


As with menus, they begin with an identifying key word (ACCELTABLE) fol¬ 
lowed by an ID, which for the main accelerator table of any application is the 
same as the menu’s ID. The description of the table is enclosed in a 
BEGIN/END block. 
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Each line of the table has at least three elements. The first element is either a 
character enclosed in double quotes, a VK_* constant (remember to include 
OS2.H), or a numeric scan code. (The scan code is keyboard-specific, so you 
wouldn’t ordinarily use that.) The second element is the command generated 
by the hot-key. 

Chapter 6 contains a list of VK_* constants. 

The third element describes the first element, and therefore is either CHAR, 
VIRTUALKEY, or SCANCODE. (As discussed, CHAR is optional as long as 
there is some third element.) There is also a LONEKEY option that allows you 
to require that a key be pressed and released without any other keys being 
pressed in between. 


Subsequent elements (separated from the third element by commas) can be 
CONTROL, SHIFT, or ALT, indicating that the key must be pressed in conjunc¬ 
tion with one of those keys. You can also specify SYSCOMMAND or HELP to 
cause the hot-key to generate WMJ5YSCOMMAND or WM_HELP messages, 
instead of the default WM_COMMAND. 



When specifying an accelerator table that uses several key chords involving 
the same key, specify the more restrictive hot-keys first. So, if you used Fll, 
Shift+Fll, and Ctrl+Shift+Fll, you would first describe Ctrl+Shift+Fll, then 
Shift+Fl 1, and finally Fll. 

Add the accelerator table description to the resource file and try it out. 



Don’t forget to remove the ~FCF_ACCELTABLE in the flag options initializa¬ 
tion: 

ULONG f1FrameOpts = FCF_STANDARD & ~FCF_IC0N; 


Otherwise the accelerator table won't be loaded. 


So as not to belabor this fairly simple feature, I’ll just direct your attention to 
two features of the accelerator table: 


The accelerator table doesn’t have to match the menu. Notice that I 
added a hot-key to create the CMD_VAR1ABLE command even though 
that menu item’s string gives no clue that a hot-key can be used. (This is 
not a good thing, but you should be aware that it can happen.) 

The accelerator table isn’t completely independent of the menu. To 
understand what I mean, run the program and press v. It works just as if 
you had selected Variable from the menu. Now press Ctrl+D to disable 
the item and verify that it is disabled in the pull-down menu. Now press 
v again—nothing happens! 
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This means that you don’t have to worry about catching commands coming 
from hot-keys if you’ve disabled the menu item that creates those commands, 
which is a useful bit of knowledge indeed. 


Conclusion 

Menus respond to many more messages than the ones described in this 
chapter. You can dynamically create entire menu structures simply by send- 
ing messages to a menu window. 

As I stated up front, however, menus are not as important as they used to be, 
and may even be going out of style in favor of toolbars. So, let’s leave the dis¬ 
cussion of menus for now and head on to more fun thngs: bitmaps, icons, and 
pointers. 


The 5th Wave 
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Chapter 8 

Bitmaps, Icons, and Pointers 

/« This Chapter 
Using custom icons 
Creating pointers 
Using custom and system pointers 
Bitmap drawing 


m # ne ° f the reasons 1 didn,t want to dwell on displaying text in an applica- 
tion (remember Chapter 4, “Getting Your Feet Wet and GUI”?) is that 
text is, well, boring! Also, now that we have a cool graphical user interface 
like WPS, our applications should be graphical! 


Probably the most recognizable elements of Warp are its icons. Unlike some 
GUIs, Warp doesn’t start by opening windows (unless you tell it to). Instead, 
it displays icons that mean something to the user. (Even the LaunchPad is lit¬ 
tle more than a bunch of icons conveniently clustered together.) 


Of course, the pointer is also part of Warp and is another graphical item we 
can manipulate. 


And, if you have an image coloring your Desktop—I favor the pool—then you 
have experience with Warp’s bitmaps. 

OS/2 contains powerful API functions for manipulating graphics in the form of 
approximately 250 GPI calls. But we can begin to incorporate graphics into an 
application without using any of them! 
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Icons 101 

Fire up the icon editor for this example and create a simple icon. Call it 
TESTICO.ICO, as shown in Figure 8-1, and save it in the same directory as one 
of your programs, preferably one that has a resource file already. Keep the 
icon editor handy, because we’ll be using it a lot in this chapter. 


Figure 8-1: 
My 

TESTICO.ICO. 
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Form Size : 32x32 


Form name : 
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Pen Size : 1x1 


Hotspot : 16x16 


Screen 



The icon editor comes with the OS/2 Developer’s Toolbox, with most other 
compiler packages, and with OS/2 Warp (in the Productivity folder of the 
OS/2 System folder). 

You can create an icon by selecting File I New and choosing the Icon radio 
button from the dialog. When you save the icon, save it in 2.0 format. 


Add the following line to the program’s resource file (or create a resource 
file, if necessary). 


DEFAULTICON <testico.ico> 


Compile the resource and link it into the program’s executable. You don’t 
need to recompile the program for this. In fact, that’s part of the point of 
using resources in the first place: Merely changing the resource file doesn’t 
force you to recompile your entire program. 
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If you run this, you may be disappointed. Nothing about the app appears to 
change. But, if you now track down the program in its directory by using the 
drive object, or if you create a new Desktop object to run the program, you’ll 
discover that your icon is used to represent the program on the Desktop. 

DEFAULTICON loads an icon into the file’s Extended Attributes (EAs) so that 
it will be used to represent the program by default. If you minimize the icon 
and open the Minimized Window Viewer object, you’ll observe that your icon 
is used to represent the minimized window as well. 

To add an icon to your application so that it actually appears as the system 
menu icon (instead of the rather drab default), you must add an icon 
resource. 


ICON IconID filename 


IconID will be the same as the main menu’s ID and the accelerator table’s ID. 
(See Chapter 7’s discussion of menus.) The FCFJCON option must be speci¬ 
fied in the frame options for your window, too, or WinCreateStdWindow will 
never look for the icon. 



If you have a menu bar, an accelerator table, and an icon, your frame options 
initialization can look like this: 

ULONG flFrameOpts = FCF_STANDARD; 


Specifying an application icon removes any need to specify the DEFAULTI¬ 
CON option. 


Icons are used primarily with containers. Even the icon we just assigned to 
represent our application shows up where? On the Desktop (a container), or 
in one of the disk drive objects (containers). We’ll look at containers in Chap¬ 
ter 26. 


Point Taken 

Although you might not think of them in these terms, icons are tools for 
communicating with the user: A good icon identifies your application at a 
glance. We usually think of output in terms of reports, charts, and so forth, 
but a program’s user interface (including icons) is a kind of output, too—and 
it makes your application more accessible. 

The pointer is another form of output that can make your program more 
accessible and understandable. You use pointer information—specifically, 
the shape of the pointer—all the time to interact with OS/2. 
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Move the pointer over a resizable frame and it becomes a double-headed 
arrow, indicating that the window may be resized. Move it over a text field 
(or word processor) and the pointer changes to look like an I (called an I- 
bearri). When WPS first starts, it turns the pointer into a clock symbol, indi¬ 
cating that you must wait before trying to interact with your Desktop. 



PM has one user interface message queue, which is shared by all of its appli¬ 
cations. While a window is handling a message in its procedure, the user may 
not interact with that window or with any other application. 

A window that ties up the message queue for too long after the user tries to 
switch tasks (through Ctrl+Esc or Alt+Esc) causes PM to pop up a dialog ask¬ 
ing whether the user wants to terminate the errant application. (Chapter 6 
touched briefly on how long tasks could be broken up through the use of the 
system timer. Chapter 21 discusses multithreading as another solution.) 


Skilled use of the pointer can be an invaluable tool. You can tell the user that 
you are busy, that some special feature is available, that a regular feature is 
not available, and so on. 


Let’s create a simple application that changes the pointer based on some 
hypothetical features. We’ll call it POINTER.C and base it on the basic appli¬ 
cation framework listed at the end of Chapter 4. 


Home-qwWn pointers 

Start up the icon editor again, and this time create a pointer called 
GRAB.PTR. Make it look like a hand or a claw, or something that looks 
grabby, if you can. Figure 8-2 shows an example. 



The icon editor has a number of crude tools such as color fills and circle and 
straight-line drawing options. One way to get a really cool looking image, 
however, is to load a preexisting icon, bitmap, or pointer, copy it to the clip¬ 
board, then copy it into your image and edit it to suit your needs. This allows 
you to create a pointer from an icon or a bitmap, or an icon from a pointer or 
a bitmap, or a bitmap from an icon or a pointer! 


Adding a pointer to a resource file is the same as adding an icon, except that 
the keyword used is, not surprisingly, POINTER: 


POINTER 10 grab.ptr 


First comes the keyword, then the ID for the pointer, then the filename. 
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Figure 8-2: 
GRAB.PTR 
(Obviously, I 
didn't follow 
my own 
advice!) 


icon. Editor .~- ; C:\Writings\warp\source\GRAB.PTR 
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In a real program with a complex resource file and a lot of special defines, 
you would identify the pointer not with a literal, such as 10, but with a sym¬ 
bol such as “GRABPOINTER,” which would be stored in a separate .H file and 
used by both the resource file and the main program. 


To keep the examples simple, I cut us a little slack in this area. But even so, 
when I went to the main program to add the grab pointer, I forgot what ID I 
had assigned the pointer. 


Three functions for incorporating your own pointers into an application are 
WinLoadPointer, WinDestroyPointer, and WinSetPointer. 


General Form: HPOINTER WinLoadPointer(HWND desktop, HMODULE 
resource, ULONG pointerlD) 

As Used: hptr = WinLoadPointer(HWND_DESKTOP, 0, 10); 

WinLoadPointer returns a handle to the pointer with the ID indicated by the 
third parameter, which comes from the resource file indicated by the second 
parameter. (As always, if the second parameter is zero, the function loads the 
value from the resource file integrated with the .EXE.) The Desktop handle 
must be passed as the first parameter. 


General Form: BOOL WinDestroyPointerGHPOINTER hptr) 
As Used: if (hptr) WinDestroyPointer(hptr); 
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WinDestroyPointer destroys the pointer associated with the handle passed. 
It’s a good idea to destroy resources when you’re finished with them. 

General Form: BOOL WinSetPointer(HWND desktop, HPOINTER hptr) 

As Used: WinSetPointer(HWND_DESKTOP, hptr); 

WinSetPointer changes the current pointer based on the image represented 
by the pointer handle passed as the second parameter. Again, the Desktop 
handle must be passed as the first parameter. 

Take the POINTER.C program and add the following code to the window pro¬ 
cedure: 


case WM_BUTT0N1D0WN: 

if (hptr) WinDestroyPointer(hptr); 

hptr = WinLoadPointer(HWND_DESKTOP, 0, 10); 

WinSetPointer(HWND_DESKTOP, hptr); 
return 0; 

The hptr variable is a local variable of the HPOINTER type, declared static so 
that it will be preserved throughout the window’s life. 


static HPOINTER hptr = NULLHANDLE; 



Again, static variables are generally a bad idea. You typically want to declare 
a structure that describes the window’s data and use WinQueryWinPtr to 
access that information. In this case, however, where the variable is being 
used only to hold one unchanging value (the hand pointer), it’s acceptable, m 


If the user clicks on the window, the pointer changes to GRAB.PTR. Try this 
and you’ll find out that it works except that as soon as the user moves the 
mouse, the pointer reverts to its normal state. 


In order to maintain a pointer in a certain (non-default) state, you must set it 
every time the mouse moves! This may seem cumbersome, but it isn’t a big 
deal at all. Simply add a handler for WM_MOUSEMOVE: 


case WM_M0USEM0VE: 

if (hptr) WinSetPointer(HWND_DESKTOP, hptr); 
return 0; 

Now the grab pointer will be retained as long as the mouse pointer remains 
over the window. (It is possible, but not generally advisable, to change the 
pointer over the whole Desktop, not just your window.) 
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System pointers 

Knowing how to create your own pointer is a good thing, but there are some 
pointers that all applications have in common. Obviously every programmer 
doesn’t have to create a new clock icon to indicate wait periods. 

Another API function called WinQuerySysPointer can help us here: 

General Form: HPOINTER WinQuerySysPointer(HWND desktop, LONG ID. 
BOOL copy) 

As Used: hptr = WinQuerySysPointer(HWND_DESKTOP, SPTR_WAIT, FALSE); 

Again, we must pass the Desktop handle as the first parameter, and then the 
pointer ID as selected from Table 8-1. The last parameter allows you to get a 


Table 8-1 System Pointers 


Pointer 

Description 

SPTFLAPPICON 

Standard application icon pointer 

SPTR_ARROW 

Arrow pointer 

SPTR_FILE 

Single file icon pointer 

SPTR_FOLDER 

Folder icon pointer 

SPTRJCONERROR 

Exclamation mark icon pointer 

SPTRJCONINFORMATION 

Information icon pointer 

SPTRJCONQUESTION 

Question mark icon pointer 

SPTRJCONWARNING 

Warning icon pointer 

SPTRJLLEGAL 

Illegal operation icon pointer 

SPTRJV10VE 

Move pointer 

SPTR_MULTFILE 

Multiple files icon pointer 

SPTR_PROGRAM 

Application program icon pointer 

SPTR_SIZE 

Size pointer 

SPTR_SIZENESW 

Upward-sloping, double-headed arrow pointer 

SPTR_SIZENS 

Vertical, double-headed arrow pointer 

SPTR_SIZEWE 

Horizontal, double-headed arrow pointer 

SPTR_SIZENWSE 

Downward-sloping, double-headed arrow pointer 

SPTR_TEXT 

Text I-beam pointer 

SPTR_WAIT 

Hourglass pointer 
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copy of the pointer, which you could then alter without affecting the rest of 
the system. But since you usually don’t want to alter the pointer, you’ll set 
this parameter to false. 

Most of these pointers are put into effect by OS/2 as needed, so we don’t 
have to, for example, set the pointer to a sizing pointer when it’s positioned 
over the frame. 

However, if you write a program that allows some screen object to be resized 
(and it isn’t a standard frame window), you can change the pointer to the 
appropriate sizing pointer so the user will instantly recognize the feature. 


Bitmaps 

The last graphic element we’re going to look at in this chapter is the bitmap. 
Bitmaps are somewhat more complex than icons and pointers. You can do 
more with them and they fulfill a larger role than merely identifying an appli¬ 
cation or a pointer state. 

For this example, rather than creating your own bitmap, copy OS2LOGO.BMP 
from the \0S2\BITMAPS directory into the directory containing your source 
code. Adding a bitmap to a resource is as simple and easy as adding an icon 
or a pointer: 

BITMAP ID filename 

In this case, we’ll use: 

BITMAP 10 os21ogo.bmp 

while keeping in mind that we would use a define in a real program, not a lit¬ 
eral number such as 10. 

Although the main function of the application is the same as the one shown 
at the end of Chapter 4, the window procedure is different. We aren’t going to 
white-out the window—we’re going to draw the bitmap in it. 

MRESULT EXPENTRY ClientWndProc(HWND hwnd, ULONG msg, MPARAM mpl, 
MPARAM mp2) 

{ 

HPS hps; 

RECTL rcl; 
static HBITMAP hbmp; 

POINTL ptl; 
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/*event handler*/ 
switch(msg) { 

case WM_PAINT: 

hps = WinBeginPaint(hwnd, NULLHANDLE, NULLHANDLE); 

Wi nQueryWindowRect(hwnd, &rcl ); 

hbmp = GpiLoadBitmap(hps, 0, 10, rcl.xRight,rcl.yTop) ; 
ptl . X = 0; ptl .y =0 ; 

Wi nDrawBitmap(hps , hbmp, NULL, &ptl , 0,0, DBM_NORMAL); 
WinEndPaint(hps ); 
return 0; 


} 

/*end event handlers */ 

return WinDefWindowProc(hwnd, msg, mpl, mp2); 
} 


There are two new calls here: GpiLoadBitmap and WinDrawBitmap. Both of 
them give you a considerable amount of freedom in manipulating bitmaps. 

General Form: HBITMAP GpiLoadBitmap(HPS hps, HMODULE resource, 

ULONG ID, LONG stretchX, LONG stretchy); 

As Used: hbmp = GpiLoadBitmap(hps , 0, 10, rcl.xRight,rcl.yTop) ; 

GpiLoadBitmap requires a presentation space, the resource module (or zero 
for the resource module integrated with the .EXE file), and the resource ID. 
The last two parameters allow you to stretch the bitmap so that it takes up a 
specific amount of space, so I used them to make the bitmap fill the entire 
window. They can be specified as zero, allowing the bitmap to be displayed 
at its normal size. GpiLoadBitmap returns the handle to the bitmap 
requested. 

General Form: BOOL WinDrawBitmap(HPS hps, HBITMAP hbmp, PRECTL 

portion, POINTL target, LONG forecolor, LONG backcolor, 
ULONG opts) 

As Used: WinDrawBitmap(hps, hbmp, NULL, &ptl, 0,0, DBM_NORMAL); 

WinDrawBitmap requires the presentation space, the handle to the bitmap 
(usually retrieved by GpiLoadBitmap), the portion of the bitmap that you 
want to draw (or NULL for the whole thing), the desired location for the 
bitmap’s lower left-hand corner, and the foreground and background colors 
(which are ignored if the bitmap is not a monochrome bitmap). The last para¬ 
meter specifies any number of options, but DBM_NORMAL is all we’ll use for 
now. It draws the bitmap normally. 

We’ll look at fancier tricks with bitmaps in Chapter 18. 



132 


Part El Resources and Dialogs—Getting in Touch with Your OS 



Besides bitmaps that you load with WinLoadBitmap, OS/2 has a number of 
system bitmaps that you can access with WinGetSysBitmap: 

General Form: HBITMAP WinGetSysBitmap(hwnd HWND, ULONG id) 


The ID may be any of a number of constants, such as SBMPJJPARROW, but 
these bitmaps are not usually of much use, so 1 won’t use up space on them 
here. (You can find the complete list of system bitmaps under the WinGet¬ 
SysBitmap entry in the PM programmer’s guide and reference. 


Conclusion 

This was an easy chapter, wasn’t it? If you’re reading this book sequentially, 
you’re probably getting a feel for how PM works and how OS/2 is structured. 
You also should be fairly comfortable with resource files, at least with regard 
to the areas that we’ve covered. 

That’s good, because after a short chapter on using standard dialogs (coming 
up next), we’ll see how resource files can be used to express objects far more 
complex than icons or pointers, or even menus. 
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An Introduction to Dialogs 
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m JPne thing that computer programmers really love to do is drop letters off 
the ends of words. “Catalogue” becomes “catalog,” “directory” becomes 
“dir,” “disc” becomes the diminutive “diskette,” which then gets shortened to 
“disk,” and on and on. 


So naturally, when you want the user to interact with your program—when 
you want to engage in a dialogue with the user—you put up a dialog. 

First things first: What is a dialog, and how is it different from a window? This 
is one of those profound programmer questions which is best answered with 
a firm “It depends.” 

The traditional view of the dialog can be seen in just about any OS/2 program 
that lets you open or save a disk file. OS/2 has a standard file dialog, shown in 
Figure 9-1, that any program can call up. 

Typically, when you see this dialog you know that you can’t do anything else 
in the program you’re working in—maybe not even the entire system—until 
you select a file. This is the concept of modality , which we’ve touched on 
briefly in other chapters. Modality is traditionally the signature of the dialog. 
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If you call up a settings notebook, as shown in Figure 9-2, you’ll see that it 
looks similar to a file dialog, or can , but it isn’t at all modal. But a settings 
notebook is a dialog, even though it isn’t modal. 

What do the two have in common? They both contain buttons, and maybe a 
list box or an entry field—window classes known as controls. So, we can say 
this much about a dialog: It has controls. 

A good generic description of a dialog is: “Any frame window, and its chil¬ 
dren, created for the express purpose of retrieving a specific subset of infor¬ 
mation from the user. Often a dialog also restricts access to other parts of 
the program, and this is called modality .” 



0.Helv 


Figure 9-2: 
The Desktop 
settings 
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For example, if you write a word processing program and you want users to 
be able to open disk files, you display a file dialog in which they can specify 
which file to open. The main word processor window doesn’t count as a dia¬ 
log because it’s not limited to retrieving a specific subset of information. 

But if you’re letting users design a style sheet for a document, you would usu¬ 
ally display a dialog, and it might call up several others. A dialog like this 
would probably be modal—you wouldn’t want to allow the users to type 
information into the document until they’d responded to the dialog. 

This distinction is important because it is not ideal! We won’t see the dialog 
vanish any time soon, but if we adhere to the principle that direct, modeless 
manipulation is best, then a better solution for opening files is to enable the 
word processor to interact with the drives folder. Let the user select a docu¬ 
ment by dragging it out of a folder and dropping it onto the word processing 
window. 


Similarly, a style sheet could be an object, too, and the user could open up a 
folder of style sheets and drop them on a document to format it. The mecha¬ 
nism for creating a style sheet could be entirely independent of the word 
processor. 


In actual practice, it’s often easier to type in a name than to deal with all the 
windows—but that’s not really consistent with the way WPS works. 



We should be aware when we’re using technologies that are somewhat old- 
fashioned, and make sure that we’re using them because they’re convenient 
for the user, not because we don’t know any better. 

Direct manipulation and WPS solutions are covered in Chapters 24, 25, and 26. 


Message Boxes 

One of the most common and useful tools of the programmer is the message 
box. The message box is a simple little dialog presenting a message and up to 
three buttons for the user to choose from. 

General Form: ULONG WinMessageBox(HWND parent, HWND owner, PSZ 
text, PSZ title, LONG id, LONG options); 

As Used: cmd = WinMessageBox(HWND_DESKTOP, hwnd, 

"Do you want to save your work before exiting?", 

"Query", 0, MB_YESNOCANCEL | MB_QUERY); 

WinMessageBox pops up a message dialog box. No big surprise, I’m sure, just 
as I’m sure you’ve seen many message boxes while using Warp. 
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The parameters to WinMessageBox should be pretty clear to you just by 
their names. The dialog’s parent is usually HWND_DESKTOP, because you 
want to make sure that the box will have enough room to display itself fully. 
The dialog’s owner is usually your client window. (More on ownership and 
parenthood just ahead.) The title appears at the top of the box, and the text 
appears below it. You can assign the dialog an ID number with the penulti¬ 
mate parameter (in case you need to do a WinWindowFromID or something). 


The message box options repeated! 

The last parameter is a bit mask with several groups of options. The first 
group concerns which pushbutton should appear in the message box. 
Exactly one of the following may be selected (MB_OK is the default): 

MB_ABORTRETRYIGNORE MB_CANCEL MB_ENTER 

MB_ENTERCANCEL MB_HELP MB_0K 

MB_OKCANCEL MB_RETRYCANCEL MB_YESN0 

MB_YESNOCANCEL 

I don’t have to explain, I’m sure, that MB_ABORTRETRYIGNORE puts three 
buttons on the message box, labeled Abort, Retry, and Ignore, and that 
MB_CANCEL puts just one button on the message box, labeled Cancel. 

The next group of options concerns what icon will appear in the message 
box. As their meanings are not as obvious as those of the button options, the 
icon options are listed in Table 9-1. Exactly one may be specified. 


Table 9-1 WinMessageBox Icon Options 

Option 

Description 

MB_ERR0R 

A red circle with a diagonal line through it (the "No" sign). 

MBJCONASTERISK 

Same as MBJNFORMATION. 

MBJCONEXCLAMATION 

Same as MB_WARNING. 

MBJCONHAND 

Same as MB_ERR0R. 

MBJCONQUESTION 

Same as MBJ1UERY. 

MBJNFORMATION 

The information icon: an /in a blue circle. 

MBJMOICON 

No icon appears. 

MB_QUERY 

A white question mark (?) in a green circle. 

MBJ/VARNING 

A white exclamation point (!) in a cyan triangle. 
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The MB JCON* constants appear to be left over from an earlier version of 
OS/2—from a time when the palm of a hand (the universal sign for stop, I 
guess) meant an error had occurred. 

You don’t need to specify MBJNOICON to not get an icon. If you don’t specify 
any of these options, you won’t get an icon. 

The appropriate system sounds accompany these icons: beeps from com¬ 
puter speakers, and more elaborate snaps, crackles, and pops from systems 
with sound cards. 


After specifying the buttons that should appear on the message box, you can 
also specify which button should be the default with MB_DEFBUTTONl, 
MB_DEFBUTTON2, or MB_DEFBUTT0N3. The default button will be the one 
with the focus when the message box first appears. Generally, you should 
select the least destructive option to be the default. That way, if users press 
Enter without changing the focus (as impatient users are wont to do when 
they see a message box), they’ll cause the least damage. 

Message boxes are modal: When a message box pops up, its owner is dis¬ 
abled. That’s why you don’t want to specify the client window as both the 
parent and the owner. If the message box is owned by the client window and 
the client window is disabled, you’ve created a situation that makes it impos¬ 
sible to dismiss the message box. ‘Of course, I had to try this, and all I found 
was that the program was likely to crash.’ 


Disabling the owning window is the default action, but you can express it 
explicitly through the MB_APPLMODAL option. You can also disable the 
entire system by setting the MB_SYSMODAL option. 



Don’t make your message box system modal unless you have a really, really 
good reason for it. Imagine multitasking happily when a program running in 
the background suddenly blocks all your input to send you a message. It had 
better be telling you that your chair is on fire! 


OS/2 uses system modal dialog boxes to report critical problems. 


Finally, you can specify that the user can move the message box with the 
MB_MOVEABLE option. Just make sure that the message box gets a system 
menu that includes Close as an option. If the user selects Close, the message 
box will return the same value as if the Cancel button had been pressed— 
even if no Cancel button exists on the dialog. 



138 


Part ft Resources and Dialogs—Getting in Touch with Your OS 


The message box returns 

The message box returns a code based on which button was pressed: 



MB ID_ENTER 
MB ID_RETRY 
MBID_ERR0R 


MBID_0K MBID_Y ES 

MBID_IGNORE MBID_ABORT 

MBID_CANCEL MBID_N 0 


A message box can return MBID_CANCEL, even if there is no Cancel button, 
when the MB_MOVEABLE option is selected. 


WinMessageBox guick reference 

For your reference, here are the message box options again, listed in a com¬ 
pact format you can refer to, and with defaults italicized: 

Pushbutton Options 
MB_ABORTRETRY IGNORE 
MB_ENTERCANCEL 
MB_OKCANCEL 
MB_YESNOCANCEL 

Default Button Options 

MB_DEFBUTT0N1 

Icon Options 

MB_ERR0R 
MB_QUERY 

Modal Options 

MB_APPLMODAL 

Moveable Options 
MB_MOVEABLE 


Basic Error Stuff 

Up until now, I’ve glossed over most discussions of what several crucial func¬ 
tions return. For example, what happens if WinCreateStdWindow fails? The 
application just never shows up, although as I mentioned in Chapter 7, it 
does get loaded into the system invisibly, where it can cause trouble (at least 
for us programmers). 


MB_CANCEL 

MB_HELP 

MB_RETRYCANCEL 


MB_D EFBUTT0N2 


MB_INFORMATION 
MB_WARNING 


MB_SYSMODAL 


MB_ENTER 

MB_0K 

MB_YESN0 


MB_DEFBUTT0N3 


MB_N0 1 CON 
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Obviously it’s best to avoid this kind of situation, but it’s not entirely accept¬ 
able to stealthily end your window without so much as a “by your leave” to 
the user. Without a standard window, we had no way of communicating with 
the user until now, which is why I never got into it before. Generally speaking, 
if any of the calls we make to create our application fail, it will be impossible 
for us to run our program. If WinCreateStdWindow doesn’t work, then we 
have no way of interacting with the user. If WinCreateMsgQueue doesn’t 
work, we’ll never get any messages. WinCreateStdWindow can’t work if Win- 
RegisterClass fails, and so on. 

Before starting the message loop then, we should check to make sure that all 
our calls succeeded. If any failed, we should notify the user and not enter the 
message loop: 

if /* didn't successfully initialize application */ 

WinMessageBox(HWND_DESKTOP, HWND_DESKTOP, 

"Unable to initialize application.", "ERROR!", 

0, MB_CANCEL | MB_ERR0R); 

This is a good thing for us as programmers to include, too. If we change 
something in a program that makes one of the basic calls fail, we have to go 
through extra steps to kill the invisible process, and might even have to 
reboot. We’ll see this code in action in the upcoming section entitled “A New 
Basic Application Framework.” 


Debugging u/ith Debug Sox 

Although debugging under OS/2 can be a daunting and complex task, particu¬ 
larly given the complexity (and instability) of graphical debuggers, you can 
use the WinMessageBox function to create a simple little tracing tool: 


#define DebugBox(title, text) \ 

WinMessageBox( HWND_DESKTOP, HWND_DESKTOP,\ 

(PSZ) text, (PSZ) title, 0,\ 

MB_0K | MB_INFORMATION | MB_MOVEABLE) 

You can then do things like: 


DebugBoxC"Info", 
/* code */ 
sprintf(message, 
DebugBoxC"Info", 
/* code */ 
sprintf(message, 
DebugBoxC"Info", 


"Made it this far!"); 

"Var has a value of %d", var); 
message); 

"Var has a value of %d", var); 
message); 
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Although this practice is a bit primitive, it can be very handy in places where 
mysterious things are happening, if you aren’t using a tool with a well- 
integrated debugger. 


Quit It! 

Up until now, our basic message loop looked like this: 

while (WinGetMsg(hab, &qmsg, 0, 0, 0)) 

WinDispatchMsg(hab, &qmsg); 

Actually, this While loop remains more or less unchanged for the rest of this 
book because, although it is possible to break up WinGetMsg and WinDis- 
patchMsg to handle messages differently, we won’t be doing it here. Roughly, 
the code would look something like this: 

WinGetMsg(hab, &qmsg, 0, 0, 0); 

/* do stuff with qmsg here */ 

WinDispatchMsg(hab, &qmsg); 

And this would be contained in an outer loop that ended when the user 
closed the window. The outer loop is what we’re going to look at. If this were 
a simple universe, and OS/2 were a simple OS, you might expect the code to 
look something like this: 

while(TRUE) { 

while (WinGetMsgChab, &qmsg, 0, 0, 0)) 

WinDispatchMsg(hab, &qmsg); 

if (WinMessageBox(HWND_DESKTOP, hwndClient, 

"Do you really want to quit now?", 

"Exit Application", 

0, MB_YESN0 MB_QUERY ) == MB I D_Y ES) 
break; 

} 


When users choose to close your application, whether by pressing Alt+F4, by 
pressing Delete while the window is selected in the Task List, or by shutting 
down the system, you may want to intercede by asking whether or not they 
really want to quit. You can do that by containing the message loop in a loop 
that can be exited only by the correct response to a message box. 
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But if users are in the process of shutting down the system, and then change 
their minds when your application asks “Do you really want to quit?”, it 
becomes your application’s responsibility to cancel the shutdown. You can 
detect a shutdown by checking qmsg’s hwnd field, which will be a 
NULLHANDLE. 

if (qmsg.hwnd == NULLHANDLE) /^system shutdown */ 

if (appState != USERQUIT) WinCancelShutdown(hmq, FALSE); 

WinCancelShutdown is a request from you to OS/2 to not shut down the 
system. 

General Form: BOOL WinCancelShutdown(HMQ queue, ULONG ignore); 

As Used: WinCancelShutdown(hmq, FALSE); 

You can also call WinCancelShutdown with the ignore parameter set to 
TRUE, and OS/2 will never send your application a WM_QUIT message gener¬ 
ated by a shutdown. In other words, it will shut down everything without ask¬ 
ing your application if it’s okay! 

I would prefer not to use the outer loop. I would rather assume that users 
really did want to shut down. To verify, I’d intercept the WM_CLOSE message 
inside the window application, and check to see whether there’s any unsaved 
work. If there were, I would give users the option to save their work or to 
cancel closing the window: 

case WM_CLOSE: 

switch (WinMessageBox(HWND_DESKTOP, hwnd, 

"Do you want to save your work before exiting?", 

"Query", 0, MB_YESNOCANCEL | MB_QUERY)) { 
case MB ID_N0: break; 
case MB ID_Y ES: /* save work */; break; 
case MB ID_CANC E L: return 0; 

Note that it’s WinDefWindowProc that turns the WM_CLOSE into a WM_QUIT. 
By skipping over it when the user selects the Cancel button, you can keep the 
window from closing. 

Unfortunately, this doesn’t work because if the user deletes the application 
from the task window, the window never receives a WM_CLOSE message. 

So to allow users to save any work, you pretty much have to catch the 
WM_QUIT message. At the same time, if you make both the WM_CLOSE mes¬ 
sage and the WM_QUIT message verify the user’s intentions, users closing 
the window by using Alt+F4 will be asked twice if they really want to quit. 
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There is also a WM_SAVEAPPLICATION message that the system sends to a 
window before closing it. Without knowing whether the message requires a 
WinCancelShutdown, you’re still stuck processing the WM_QUIT message in 
the outer loop. 


In the new basic application framework that follows, I created a special com¬ 
mand for verification that is sent by the WM_QUIT handling code, and that 
returns what button the user pressed in the verification dialog. 


A New Basic Application Framework 

Here’s the new basic application framework we’ll be using from this point 
forward: 

//define INCL_GPI 
//define INCL_WIN 
//include <os2.h> 

//include <string.h> 

//include "basic2.h" 

MRESULT EXPENTRY ClientWndProc(HWND, ULONG, MPARAM, MPARAM); 

//define APPNORMAL 0 
//define INITFAI LURE -1 
//define USERQUIT -2 

int main (void) 


HAB 

hab; 


/* anchor 

block handle 

*/ 

HMQ 

hmq; 


/* message 

queue handle 

*/ 

HWND 

hwndFrame, hwndClient; 

/* handles 

to windows 

*/ 

QMSG 

qmsg; 


/* message 


*/ 

char 

szClassName[] = 

"Basic 

Application 

Framework ][' 


char 

szWindowTi11e[ ] 

= "Your 

Window Name Here"; 



ULONG f1FrameOpts = FCF_STANDARD; 

ULONG appState = APPNORMAL; 

hab = Winlnitialize(0); 

hmq = WinCreateMsgQueue(hab , 0); 

if (!WinRegisterClass(hab, szClassName, ClientWndProc, 
CS_SIZEREDRAW, 0)) 
appState = INITFAILURE; 

hwndFrame = WinCreateStdWindow(HWND_DESKTOP, WS_VISIBLE, 
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&f1FrameOpts, szClassName, 
szWindowTitle, 0L, 0, 
BASIC2PR0GRAMID, 

&hwndClient); 

if ((appState==INITFAILURE) || (hab==NULLHANDLE) || 

(hmq==NULLHANDLE) || (hwndFrame==NULLHANDLE)) 
WinMessageBox(HWND_DESKTOP, HWND_DESKTOP, 

"Unable to initialize application.", "ERROR! 
0, MB_CANCEL | MB_ERR0R); 

el se 

while (appState==APPNORMAL) { 

while (WinGetMsg(hab, &qmsg, 0, 0, 0)) 

Win DispatchMsg(hab , &qmsg); 


if (WinSendMsg(hwndClient, WM_COMMAND, 

MPFR0M2SHORT(CMD_VERIFY, 0), 0) != MBID_CANCEL) 
appState = USERQUIT; 

if (qmsg.hwnd == NULLHANDLE) /^system shutdown */ 

if (appState != USERQUIT) WinCancelShutdown(hmq, FALSE); 

} 


WinDestroyWindow(hwndFrame); 
WinDestroyMsgQueue(hmq); 

WinTerminate(hab); 

return 0; 

1 


MRESULT EXPENTRY ClientWndProc(HWND hwnd, ULONG msg, MPARAM mpl, 
MPARAM mp2) 

{ 

HPS hps; 

RECTL rcl ; 

ULONG cmd; 

/*event handler*/ 
switch(msg) { 

case WM_PAINT: 

hps = WinBeginPaint(hwnd, NULLHANDLE, NULLHANDLE); 

WinQueryWindowRect(hwnd, &rcl ); 

WinFi11Rect(hps, &rcl , CLR_BACKGROUND); 

WinEndPaint(hps ); 
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return 0; 

case WM_COMMAND: 

switch(SHORTlFROMMP(mpl)) { 
case CMD_VERIFY: 
cmd = MB ID_N0; 

/* if (data_modified) */ { 

cmd = Wi nMessageBoxCHWND_DESKTOP, hwnd, 

"Do you want to save your work before exiting?", 
"Query", 0, MB_YESNOCANCEL | MB_QUERY); 

/* if cmd==MB_YES save_data */ 

} 

return (MRESULT)cmd; 

/* case CMD_OTHERCOMMANDS: */ 

} /* end WM_COMMAND messages */ 

} /*end event handlers */ 
return WinDefWindowProc(hwnd, msg, mpl, mp2); 

} 


Notice that, as much as I have tried to, we can no longer hold the framework 
in just one file. The contents of the BASIC2.H header file are not especially 
significant: 

#define BASIC2PR0GRAMID 1000 


#define CMD_HELP 1001 

#define CMD_VERIFY 1002 

#define MID_FILE 2000 

#define CMD_FILEOPEN 2001 


And, because most applications end up with a menu, an accelerator table, 
and a custom icon, I’ve included the BASIC2.RC file, which defines an outline 
for resources: 

#include <os2.h> 

#include "basic2.h" 

ICON BASIC2PR0GRAMID mahjongg.ico 

MENU BASIC2PR0GRAMID 
BEGIN 

SUBMENU "-File",MID_FILE 
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BEGIN 

MENUITEM "~Open\tCtrl+0",CMD_FILEOPEN 
MENUITEM SEPARATOR 
END 
END 

ACCELTABLE BASIC2PR0GRAMID 
BEGIN 

VK_F1, CMD_HELP, VIRTUALKEY,' HELP 

END 

You can copy over the MAHJONGG.ICO file from your \OS2\APPS directory. I 
picked MAHJONNG because it seems to be the only icon file that comes with 
Warp. Feel free to use any OS/2 .ICO file you like. 


The Fife Dialog 

Let’s move on to look briefly at a more sophisticated dialog. Warp has a stan¬ 
dard File dialog, which you have doubtless seen on numerous occasions in 
many different applications. The reason it looks the same from application to 
application is that Warp has a function, called WinFileDlg, that allows a pro¬ 
gram to create an instance of the standard File dialog. 

General Form: HWND WinFi1eDlg(HWND parent, HWND owner, FILEDLG fd) 
As Used: filedlg = WinFi1eDlg(HWND_DEKST0P, hwnd, fd) 


WinFileDlg is deceptively simple: The first parameter is the parent, usually 
the Desktop because you always want to make sure that the entire dialog has 
enough space to display itself. The second parameter is the owner, usually 
your client window so that it can receive any commands sent by the dialog. 
The last parameter, of type FILEDLG, is the killer. It’s a structure describing 
your specification of the many options available with WinFileDlg. 



One of the disadvantages to using a dialog compared to using direct manipu¬ 
lation (that is, enabling your program to work with WPS disk objects) is that 
even a standard dialog like this one is incredibly complex, while offering only 
part of the functionality of a dedicated object. 


An application that uses the drives folder as its “file dialog” has only to 
accept dropped files and act accordingly. 


It isn’t necessary for you to understand a lot of the flexibility of WinFileDlg 
right now (or ever, in some cases), so Table 9-2 describes selected fields from 
the FILEDLG structure. 
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Table 9-2 Selected FILEDLG Fields 

Field 

Purpose 

cbSize 

Flolds the size of the structure. 

fl 

Option flags (see Table 9-3). 

IReturn 

DID_0K or DID_CANCEL. 

papszFQFileName 

A pointerto an array of fully qualified filenames, used in a 
multiple-selection file dialog. 

pszTitle 

Dialog title. 

pszOKButton 

The text that appears on the dialog's OK (acceptance) 
button. 

szFullFile 

File mask/filename. 

ulFQFCount 

The number of entries in papszFQFFileName. Used in a 
multiple-selection file dialog. 

X 

Horizontal position. 

y 

Vertical position. 



Like the FONTMETRICS structure discussed in Chapter 4, the first field of 
FILEDLG is cbSize, containing the size of the structure. 

As with FONTMETRICS, making the size variable allows IBM to add to the 
structure in later versions of OS/2 while retaining backward compatibility 
with programs written for earlier versions. 



The second field, fl, is a bit mask set from various options, some of which are 
shown in Table 9-3. 

Modeless dialog handling is covered in the next chapter and in Chapter 25. 
The FDS_MODELESS and FDS_APPLYBUTTON options are included here only 
for your future reference. 

Another field is IReturn, set to either DID_OK or DID_CANCEL, depending on 
which button the user chooses to dismiss the dialog. 


If you create the dialog with the FDS_MULTIPLESEL option on, you can use 
the ulFQFCount field to determine how many files were selected, and the pap- 
szFQFileName array to determine what the names of those files are. 


It can be useful to set the pszOKButton text if you want the OK button to read 
Load or Open. Actually, it could even read delete and you could use the dia- 
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Table 9-3 Selected File Dialog Options 

Option 

Description 

FDS_APPLYBUTTON 

Give the dialog an Apply pushbutton. Used when the 
dialog is modeless. 

FDS_CENTER 

The dialog is positioned in the center of its parent 
window. (Takes precedence over x and y fields 
of FILEDLG.) 

FDS_ENABLEFILELB 

Applies only to a “Save as" file dialog. When set, this 
enables the file listbox. 

FDSJHELPBUTTON 

Give the dialog a Help pushbutton. 

FDSJVIODELESS 

Make the dialog modeless. 

FDS_MULTiPLESEL 

Allow the user to select multiple files. 

FDSJDPENJDIALOG 

The dialog's input line reads "Open filename:". The file 
list box is enabled. 

FDS_SAVEAS_DIALOG 

The dialog's input line reads "Save as filename:". The 
file list box is disabled unless FDS_ENABLEFILELB 
is set. 


log as a way to allow the user to select files to delete except for the text over 
the input line, which will read either “Open filename:” or “Save as filename:”. 

We aren’t going to do it here, because it’s way too involved, but it is possible 
to customize the File dialog using resource files and WinFileDlg. 

After all that, the steps to call up a file dialog are really pretty simple: 

| v* Clear the FILEDLG structure so that any unused options are set to NULL. 

I v* Set the fields of the FILEDLG structure that you are interested in. 
v* Call WinFileDlg. 

v* Fetch the filename or filenames from the FILEDLG structure. 

Here’s a snippet that you can plug into any of the basic application frame¬ 
work client window procedures: 


HWND fdlg; 

FILEDLG fd; 

char fdTitie[] = "Sample File Dialog"; 



H8 


Part II Resources and Dialogs—Getting in Touch with Your OS 


case WM_BUTT0N1CLICK: 

/* set up the dialog data */ 

memset(&fd, 0, sizeof(FILEDLG)); 

fd.cbSize = sizeof(FILEDLG); 

fd.fl = FDS_CENTER | FDS_0PEN_DIAL0G; 

strcpy(fd.szFul1Fi1e, 

fd.pszTitle = fdTitle; 

/* cal 1 up the dia 1og */ 

fdlg = WinFi1eDlg(HWND_DESKTOP, hwnd, &fd); 

/* if the user pressed OK, get the file name */ 
if (fdlg && (fd.1 Return == DID_0K)) 

WinMessageBox(HWND_DESKTOP, hwnd, 

fd.szFul1Fi1e, "File Selected", 0, 0); 

break; 


Of course, it can be a lot more complex, but this serves a lot of basic needs. 


Conclusion 

You may wonder at this point if there are any other standard dialogs in OS/2 
that you can use. There is one other standard dialog, the Font dialog. The 
Font dialog, however, makes the File dialog look short and simple by compar¬ 
ison. 

The same admonition I gave you earlier about direct manipulation applies to 
the Font dialog and the File dialog. If your application can accept fonts being 
dropped on it (from the font object) you needn’t deal with this dialog at all. 

And, unlike the File dialog, this is a viable solution for changing fonts, 
because the user needs to do far less burrowing around. 


Standard dialogs are fine, but they’ll only take you so far. The next chapter 
deals with building your own dialogs. 
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tandard dialogs can take you only so far. Most programs will define one 
or more dialogs for their own special needs. 



Again, the dialog—particularly the modal dialog, which shuts off the rest of 
the application when it is invoked—is not the preferred solution for WPS 
applications. 

Still, even WPS objects have a modeless settings dialog (notebook), so this 
chapter contains important information that you’ll use in just about every 
application you write. 



A dialog can be created by adding statements to a resource (.RC) file, but 
this is not the common approach. A dialog is typically created using a 
resource editor. The IBM Toolkit comes with such an editor, as does the 
Watcom compiler. The tool these suites use is called the Dialog Editor. 


Borland C++ for OS/2 comes with the most full-featured resource editor of the 
three: Its resource editor allows you to create menus, bitmaps, dialogs, accel¬ 
erator tables, fonts and so on, all without typing text into a resource file. Bor¬ 
land’s resource editor is called the Resource Workshop. 


If you like your compiler but would prefer a better resource editor than the 
one it provides, stand-alone resource editors such as Prominare Designer are 
available, which are generally superior to the “giveaways” bundled with most 
compilers. Chapter 27 gives Prominare’s address and phone number. 
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In this and subsequent chapters, I’ll include pictures of dialogs for you to 
recreate with your resource editor, and we’ll occasionally take a peek at the 
generated resource file to gain some understanding of what is going on 
behind the scenes. 


Occasionally we will come back to the generated file to make some changes 
to it, as special cases require. But for now, we’re interested in basic function¬ 
ality. 



When you recreate the dialogs shown in this book, you do not need to recre¬ 
ate them exactly. As long as you use the same controls, and the same 
defines to identify them, it doesn’t really matter where the controls are in 
the dialog. 


Creating y&m Ou/n Dialogs 

Let’s start by creating a simple dialog. Copy the BASIC2.C, BASIC2.H, and 
BASIC2.RC files and give them the new names DIALOG.C, DIALOG.H, and DIA¬ 
LOG.RC, respectively. Change the BASIC2PROGRAMID define in DIALOG.H to 
DIALOGPROGRAMID, and make the same changes in the other two files. 



If you are using an IDE, as recommended, you will want to start a new project 
and add the DIALOG.* files to it. Otherwise you must create a make file or 
compile all of these elements separately on the command line. 

Now fire up your resource editor and select File I New. A plain dialog appears 
in the editor’s client window area. 



Borland’s Resource Workshop is somewhat more complicated to work with, 
but vastly more powerful than the Dialog Editor used by IBM and Watcom. 

If you’re using the Resource Workshop, after selecting File I New Project, 
specify the resource type as .RC. When saving your work, always save it from 
this main window for the purpose of following along with this book. 


Select DLGTEMPLATE and press Enter after the main window appears. The 
Resource Workshop will open up a number of other dialogs asking you for 
information. Press Enter to accept the defaults, and eventually a dialog editor 
will open. 

At the right side of the work area you will see a bunch of icons that represent 
specific control windows such as pushbuttons, icons, and sliders. The 
classes represented by some of the icons may not be obvious until you use 
them. 
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For example, there is a picture of a globe at the top of the Dialog Editor’s edi¬ 
tor icons that you click if you want to add a bitmap to your dialog. In Bor¬ 
land’s Resource Workshop, the bitmap class is represented by a picture at 
the bottom of the tools that has scattered black dots (presumably “bits”) in 
it. Both tools have a Control menu, however, which allows you to select con¬ 
trols by name, should you get confused. 

Your mission, should you choose to accept it, is to place controls on the dia¬ 
log so as to create an effective and appropriate means for the user to supply 
input. 

At first, let’s stick with just a plain dialog, so we can get our feet wet with the 
resource editor and get familiar with the API calls for using a dialog in a pro¬ 
gram. 

Your resource editor will have some way of allowing you to specify the ID for 
the resource. In the Dialog Editor, for example, there are three input lines, 
one of which will contain an ID number for the resource. 

Just because we’re creating the dialog automatically is no reason to start 
assigning random ID numbers to our resources. Fortunately, most resource 
editors are capable of working with existing header files as well as creating 
their own. 



In the Dialog Editor, select FILE I OPEN INCLUDE and pick DIALOG.H to 
include the existing header file. You can then type in an identifier for the dia¬ 
log window and either assign an ID for it or accept the Dialog Editor’s default. 

In the Resource Workshop, select FILE I ADD TO PROJECT and pick 
DIALOG.H. Then select VIEW I IDENTIFIERS WINDOW to view the already 
defined identifiers and create new ones. 


Give the empty dialog a define of BAREDIALOGID. 

Save the plain dialog as DIALOG and then take a look at the generated file, 
which will be DIALOG.DLG for the Dialog Editor and DIALOG.RC for the 
Resource Workshop. The file that you created should look something like this: 

DLGINCLUDE 1 "DIALOG.H" 


DLGTEMPLATE BAREDIALOGID L0AD0NCALL MOVEABLE DISCARDABLE 
BEGIN 

DIALOG "Dialog Title", BAREDIALOGID, 12, 6, 148, 84, WS_VISIBLE, 
FCF_SYSMENU | FCF_TITLEBAR 

BEGIN 

END 


END 
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Essentially, however, what you’ll see is more of the resource language. 

If you’re using the Resource Workshop, you’ll have additional lines that 
describe the default buttons. 

As I said, we won’t dwell on the resource language commands for creating 
dialogs here, as you won’t normally use them. It should be sufficient to 
observe that the elements of the DIALOG command are similar to the para¬ 
meters passed to WinCreateStdWindow. (To be more precise, they’re the 
parameters passed to WinCreateWindow , WinCreateStdWindow’s more com¬ 
plex cousin.) 

If you’re using the Dialog Editor, you need to figure out how to include DIA- 
LOG.DLG with the rest of your resources. This is done with the RCINCLUDE 
command. Look at the DIALOG.RC file: 

#include <os2.h> 

//include "dialog.h’ 1 

RCINCLUDE DIALOG.DLG 

ICON DIALOGPROGRAMID mahjongg.ico 

MENU DIALOGPROGRAMID 

That’s all it takes. Like any other include files, you can have as many 
resources as you like in your .RC file. 

The DIALOG.H header file looks the same as before, except the resource edi¬ 
tor will have added the BAREDIALOGID define to it. 

You can generally tell what the resource editor has added to your header file 
by the spacing it uses, which will probably differ from yours. 

From the starting point of BASIC2.H, the resource editor added the last line 
shown: 

//define DIALOGPROGRAMID 1000 

//define CMD_HELP 1001 

//define CMD_VERIFY 1002 

//define MID_FI LE 2000 

//define CMD_FILEOPEN 2001 

//define BAREDIALOGID 100 ■ 
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Nov) that I Have a Dialog, 

What Do I Do With It? 

It’s simple to invoke a modal dialog that is part of your .EXE. The API function 
that is used to create the dialog window instance from the resource file is 
WinDlgBox. 

General Form: ULONG WinDlgBoxlHWND parent, HWND owner, PFNWP 
dlgproc, HMODULE resource, ULONG id, PVOID data); 

As Used: WinD1gBox(HWND_DESKTOP, hwnd, WinDefDlgProc, 0, 

BAREDIALOGID, NULL); 

To invoke the dialog, I attached some code to the CMDJFILEOPEN message 
handler, but you could do it by responding to BUTTON1 CLICK (as we did last 
chapter) or to any other event: 


case WM_COMMAND: 

switch!SHORT:!FROMMP(mpl)) { 
case CMD_FILEOPEN: 

WinDlgBox(HWND_DESKTOP, hwnd, WinDefDlgProc, 0, BAREDIALOGID, 
NULL); 

break; 

case CMD_VERIFY: 


WinDlgBox takes the parent, the owner, a function to handle its messages, 
the module that the dialog resides in (or 0, meaning it is in the .EXE), the dia¬ 
log ID, and a pointer to data to be used in setting up the dialog. 

For the function to handle its messages, I used WinDefDlgProc, which is used 
like WinDefWindowProc. It gives a dialog some of its characteristic behavior. 
For a fully functioning dialog, you need another function to handle dialog 
messages, as you’ll see shortly. 

The last parameter is a pointer to data that the dialog uses as it sets up. 
When created, dialogs receive a WMJNITDLG message, and the last parame¬ 
ter is passed as mp2 of the message. (More on this later.) 

If you run this code, you’ll find that the dialog appears, and you can close it 
with AIt+F4. The calling window is disabled, showing that this is truly a 
modal dialog. The user must address it before the application can continue. 
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Now, go back to the resource editor and load up DIALOG.RES. Add two but¬ 
tons to the dialog, one labeled OK and one labeled Cancel. Give them the IDs 
of DID_OK and DID_CANCEL. You’ll notice that you don’t have to add these 
defines—they exist already. 

If you’re using the Borland Resource Workshop, your dialog will automati¬ 
cally have these buttons and a Help button. 

Now you can re-make the program—which should involve only recompiling the 
resource file and reintegrating it into the .EXE—and the program will respond 
with the new dialog (see Figure 10-1). (That’s part of the beauty of resources: 
You can change them without changing or recompiling source code.) 


Figure 10-1: 

I'll have a 
plain dialog, 
with OK and 
Cancel 
sprinkles 
on it. 


The OK and Cancel buttons have predesignated purposes for dialogs. If you 
press either of them, the dialog will go away. If you want greater functionality 
from your dialog, you’ll have to create your own dialog procedure. 


Dialog procedures 

Let’s start by looking at a dialog procedure framework: 

MRESULT EXPENTRY Di al ogProc(HWND hwnd, ULONG tnsg, MPARAM mpl, 
MPARAM mp2) 
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switch(msg) { 

case WM_C0MMAND: 
/* stuff here */ 
break; 


return WinDefD1gProc(hwnd , msg, mpl, mp2); 
} 


Look familiar? It’s almost identical to ClientWndProc—the window procedure 
we’ve used throughout this book. The only visible difference is the WinDef- 
DlgProc call instead of a WinDefWindowProc call. 

Another difference is that you don’t ordinarily respond to WM_PAINT mes¬ 
sages in a dialog. A dialog is filled in with a particular color and consists of 
control windows (such as buttons and input lines) that do all the necessary 
painting. You don’t typically call WinDrawText to write on the dialog, for 
example. 


So what do you do inside a dialog’s procedure? You respond to messages 
issued by the dialog’s child controls. For example, you might respond to 
DID_OK or DID_CANCEL by dismissing the dialog. 

That’s not necessary in most basic situations, as simply passing DID_OK and 
DID_CANCEL to WinDefDlgProc will dismiss the dialog. (Explicitly dismissing 
dialogs can be useful , however, especially when the dialog is modeless, as 
we’ll discuss in the last section of this chapter.) 



As a matter of fact, WinDefDlgProc will dismiss the dialog if any WM_COM- 
MAND is passed to it. What that means is that you can give a modal dialog 
any number of buttons associated with specific commands, and never write 
any code to dismiss the dialog when those buttons are pushed, because the 
dialog is dismissed automatically. The value of the selected command is 
returned from the WinDlgBox function, so that you can act accordingly. 


Consider the dialog procedure a good place to handle other kinds of button 
messages. For example, the Enhanced Editor (EPM.EXE) in OS/2 pops up a 
dialog in response to FILE I OPEN that allows you to enter a filename. But this 
dialog also has a button that calls up a standard File dialog. 


That code might look something like: 


case DID_BR0WSE: 

if W i n F i 1 e D1 g ( . . . ) 
open_fi1e; 




[frame] 


Cancel 
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A traditional modal dialog does not have any effect until it is dismissed with 
an OK (or equivalent). But a modeless dialog might have an Apply button 
that causes changes to take place immediately. 

The slickest dialogs often have elements that correspond to each other: a 
check box is checked and a group of radio buttons becomes enabled. Or 
maybe an entirely new set of controls becomes available. 

Because a control sends its owner messages about events, the dialog proce¬ 
dure is often the place where connections between controls are realized. 
We’ll cover this in detail later, but a little example now of how this works 
won’t hurt. 

Go back to the resource editor and add two more buttons to the form. Call 
one “Cause” and the other “Effect” and give them command names of 
DID_CAUSE and DIDJEFFECT. Figure 10-2 shows an example. 


Figure 10-2: 
The Cause- 
Effect 
dialog. 


Now look at the following dialog procedure: 

MRESULT EXPENTRY DialogProc(HWND hwnd, ULONG msg, MPARAM mpl, 
MPARAM mp2) 
t 

HWND effect: 

BOOL enabled; 


ig' Dia log Edito r - dialog.res *, D1ALOG.H ___ 

lile Edit Control Arr ange Options Help 

Text: |. 

Symbol: [__ 











Chapter 10 Dialoging with Warp 


157 


switch(msg) { 

case WM_COMMAND: 

switch(SH0RT1FROMMP(mpl)){ 
case DID_CAUSE: 

effect = WinWindowFromlD(hwnd, DID_EFFECT); 
enabled = WinlsWindowEnabled(effect); 
enabled = lenabled; 

WinEnableWindow(effect, enabled); 
return 0; 

case DID_EFFECT: 

/* do something */ 
return 0; 

1 


return WinDefDlgProc(hwnd, msg, mpl, mp2): 
} 


Here again we see the WinWindowFromID function, but this time we’re using 
the ID (DID_EFFECT) that we created in the dialog editor. There are two new 
functions here, for checking to see if a window is enabled and for setting its 
enabled state: 

General Form: BOOL Wi nlsWi ndowEnabl ed(HWND hwnd); 

As Used: effect = WinlsWindowEnabled(effect); 

General Form: BOOL WinEnableWindow(HWND hwnd, BOOL on); 

As Used: WinEnableWindow(effect, enabled); 

Once we have a handle to the Effect button, we store its enabled state in a 
local variable (enabled), reverse the enabled state, and then call WinEn- 
ableWindow with the new state as a parameter. 

Nothing especially exotic here. As you can see, message handling within a 
dialog procedure is not much different from message handling within a win¬ 
dow procedure. 


Control Windows 

A quick recap: Dialogs are usually put up to obtain some information from 
the user. To obtain that information, dialogs generally own child windows, 
called controls , that serve the purpose of retrieving one specific type of data 
from the user. 
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For example, an input line retrieves one line of text. A radio button retrieves 
exactly one choice from a set. A check box retrieves zero, one, or more 
choices from a set. 

For a modal dialog to be meaningful, it must be able to interpret the user’s 
selections from its children and return that data to the calling window. If the 
data is meant to be persistent (such as color and font options for the pro¬ 
gram), the dialog should also be able to respond to a request from the calling 
window for the current settings. 

Although we’ll deal with each of the standard PM controls in greater depth in 
upcoming chapters, let’s get a feel for this whole process by changing this 
four-button dialog into something a little more realistic. 


Getting readg for dialog data 

When a dialog is first created, it is sent a message called WMJNITDLG, which 
is a little bit like receiving a phone call from your in-laws saying they will be 
over in 20 minutes. This is your last chance to fix everything up before they 
see it. 

The dialog you design with your resource editor may not be complete; you 
might want the controls to have certain values based on information you can 
get only at run-time. The WM JNITDLG message sends any information that 
the client code wants the dialog to know before setting itself up. 

Look back to the WinDlgBox function and you’ll see that the last parameter 
contains a void pointer. This pointer usually points to some kind of structure 
that you have defined specifically for code that calls the dialog. 

As an example, open up the dialog resource again, and add an entry field in 
the top left portion of the dialog (see Figure 10-3). Call the entry field 
EF_DATA. Let’s make the dialog program display a text string, and let’s use 
the dialog to allow the user to specify what the text string should be. 

First, change the window procedure to draw the text: 

static char data[1000] = "Initial Data"; 
case WM_PAINT: 

hps = WinBeginPaint(hwnd, NULLHANDLE, NULLHANDLE); 

WinQueryWindowRect(hwnd, &rcl ) ; 

WinFi11Rect(hps, &rcl, CLR_WHITE); 

WinDrawText(hps, -1, data, &rcl, 0,0, 

DT_TEXTATTRS | DT_CENTER | DT_VCENTER); 
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Figure 10-3: 

An entry 
field dialog. 
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WinEndPaint(hps) ; 
return 0; 

Now pass the data to the dialog: 

case CMD_FILEOPEN: 

Wi n D1 gBox(HWND_DESKT0P, hwnd, DialogProc, 0, 
BAREDIALOGID, data); 

break; 

The WM_INITDLG message will pass the data variable in mp2. 


Steps to using dialog data 

The successful use of dialog data requires several steps. These steps apply 
not only in this simple case of a single entry field, but also to complex modal 
and even non-modal dialogs such as notebooks. 

First, never use the passed data directly. In other words, if you receive a 
pointer to the data variable from the client code: 

case WM_INITDLG: 

client = mp2; 
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you wouldn’t normally proceed to operate on the client variable. That would 
directly (and immediately) affect the data area of the calling code. 

Instead, you typically declare a similar structure and pointer to the client 
structure: 

static char local[1000]; 
static char* client; 

and then copy the client data over into the local variable. 

case WM_I NITDLG: 

client = mp2; 

strcpy(1ocal , client); 

All operations are done on the local variable, which you then copy back over 
to the client variable if and only if the user indicates acceptance of the 
changes. (Typically through the use of the OK button.) 

case DID_0K: 

strcpy(client, 1ocal ); 

This allows the user to cancel the dialog and, by canceling, to negate any 
changes made during the life of the dialog. You don’t need to write any spe¬ 
cial code for the Cancel button since you never change anything in the client 
code until the user specifically commands it. Programmatically speaking, 
you’re off the hook. 

This would apply even to a notebook-style (non-modal) dialog, where 
changes made can affect the program while the dialog is still on screen. 

In that case, you would probably have several copies of the structure: one for 
the original data (so that the user can select Undo), one for the current data 
(what actually appears in the dialog) that would take effect in the program 
when the user selects Apply, and one for default settings. 

About the only time you would operate directly on the calling code’s data is 
when you wanted the calling code to be affected immediately, as when the 
user selects a font and you force the calling window to repaint itself with the 
new data. Even here, however, you need to keep a copy of the original data 
around in case the user changes his or her mind. 

This section covers the general steps for handling dialog data, but we need to 
look specifically at certain calls for interacting with the entry field window 
class before we can implement the code. 
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Setting and Getting Window Text 

Quite frequently communication with control windows is done with Win- 
SendMsg. This was covered extensively in Chapter 6 when virtually every bit 
of data passed to and from the scroll bars through some kind of SBM_* define 
along with the WM_COMMAND, and in Chapter 7 when we altered menu 
items. 



Scroll bars and menus are often considered control windows, too. Basically, 
any window that’s not a frame window or a client window can be called a 
control window. 

The entry field is an exception, however, because it contains text. Because 
many controls contain text and can benefit from a specific call for retrieving 
and setting that text, you can communicate quite nicely with an entry field 
window through two special function calls: 


General Form: BOOL WinSetWindowText(HWND hwnd, PSZ buf); 

As Used: WinSetWindowText(data, local); 

General Form: LONG WinQueryWindowText(HWND hwnd, LONG bufsize, PCH 
buf); 

As Used: WinQueryWindowText(data , 1000, local); 


These functions are fairly self-explanatory. The first sets text for a window 
and the second retrieves it. WinQueryWindowText will not retrieve more 
data than there is room for in the passed buffer (the third parameter), based 
on the amount passed in the second parameter. 

These are very versatile calls that can be used to change the text not only of 
entry fields, but also of frame windows (the titlebar caption is what actually 
gets changed), buttons, menus, and so on. 

We’ll use these functions twice in our code. First, we want to set the entry 
field’s data when calling it: 


WinSetWindowText(data , local); 


Then, when the dialog has been dismissed with an OK, we need to find out 
the current data so that we can copy it back: 


WinQueryWindowText(data , 1000, local); 
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The entire dialog procedure now looks like this: 

MRESULT EXPENTRY DialogProc(HWND hwnd, ULONG msg, MPARAM mpl, 
MPARAM mp2) 

{ 

HWND effect, data; 

BOOL enabled; 

static char local[1000]; 

static char* client; 

switch(msg) { 

case WM_INITDLG: 

client = mp2; 

strcpy(1ocal , client); 

data = WinWindowFromlD(hwnd, EF_DATA); 

WinSetWindowText(data, local); 
break; 

case WM_COMMAND; 

switch(SHORTlFROMMPCmpl)){ 
case DID_CAllSE: 

effect = WinWindowFromlD(hwnd, DID_EFFEOT); 
enabled = WinlsWindowEnabled(effect); 
enabled = lenabled; 

WinEnableWindow(effect, enabled); 
return 0; 

case DID_EFFECT: 

/* do something */ 
return 0; 

case DID_0K; 

data = WinWindowFromID(hwnd, EF_DATA); 

WinQueryWindowText(data , 1000, local); 
strcpy(client, 1ocal ); 

break; /* let WinDefDlg dismiss the dialog */ 

1 
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The Dialog Procedure in Full 


return WinDefDIgProc(hwnd, msg, mpl, mp2); 
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We need only one more change to make the whole program work: Even when 
the user presses OK and the data is passed back to the calling window, noth¬ 
ing happens at first because the window won’t repaint itself with the new 
data. 

It’s probably not a good idea to try to give the dialog the power to force the 
calling window to repaint, at least not in this example. It’s better to have the 
calling window check to see whether the user dismissed the dialog with the 
OK button and, if so, repaint itself: 

case WM_C0MMAND: 

switch(SH0RTlFROMMP(mpl)) { 
case CMD_FILEOPEN: 

if (W1nD1gBox(HWND_DESKTOP, hwnd, DialogProc, 0, 

BAREDIALOGID, data)==DID_0K) 

WinInvalidateRect(hwnd, NULLHANDLE, TRUE); 

break; 

Now when the user invokes the dialog, changes the text, and presses OK, the 
text displayed in the window changes accordingly. 


Dialog Modality 

A dialog is modal when it shuts off access to the rest of the program (or the 
entire system) until the user responds. Information gathered by modal 
dialogs generally takes effect only after the user OKs it. 

I’m not a big fan of modal dialogs, personally. Have you ever been working in 
a program, called up a dialog to do something, and then realized that you 
needed to access some other part of the program to fill out the dialog—only 
to find that you couldn’t? 

You have to back out of the dialog, find out the information you need, and 
then reinvoke the dialog. Then you have to hope you don’t forget the infor¬ 
mation, or hope that it will fit on screen next to the dialog. If the information 
is scattered over several windows, that makes the problem worse. 

Sometimes (I suppose) modal dialogs are necessary. If possible, however, try 
to use modeless dialogs to get information from the user. 

Modeless dialogs are covered in Chapter 25, which primarily covers WPS 
notebooks. You can have a modeless dialog that isn’t a notebook. And the 
information in Chapter 25 on modeless dialogs is applicable to all types of 
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modeless dialogs. But before getting into that area, it makes a lot more sense 
to go into control windows in greater detail, which we’ll do next. 


Conclusion 


A dialog editor (in any form) is a boon to the programmer: Without dialog 
editors, I would have had to devote page after page of this chapter to the 
resource language keywords used to describe dialogs. And you would have 
had to read it, and probably refer to it constantly, in order to build your 
dialogs. 

And the result of editing a text file to create a dialog is often far less satisfying 
than just drawing the dialog on the screen. 



In Chapter 27,1 talk about some of my favorite tools, many of which take the 
dialog editor a step further, allowing you to program from within their design 
interface, and then invoking the compiler for you. As a result, you can go 
through the complete development cycle using nothing but these tools. 


These can be incredible productivity boosters and, as many of them also 
help by supplying OS/2 API call hints, they can contribute greatly to your 
learning of the OS/2 API. 


Now, however, it is time to examine the control window classes and how you 
use them in dialogs. 








J*#ere we’ll explore the many control windows of OS/2: 
¥ m the buttons, the entry fields, and so on, that are 
major components in making up OS/2 applications. We’ll 
also become intimate with the importance of message 
sending in a PM application. 


In This Part .. 
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in This Chapter 
A different kind of framework 
Control window classes 
Control window styles, data, and messages 
The static window class 
“Callbacks” 

Tab order 

Win* calls that help dialog control 


M he next few chapters are like a plate of hors d’oeuvres. They contain no 
m radical concepts, no particularly taxing elements, nothing that should 
cause a strain to either OS/2 or you—Just an interesting assortment of new 
topics. 

In fact, you could probably skip them altogether—as long as you remember 
where they are the next time you want to build a dialog. 

This chapter is important, however, because it serves as an introduction to 
the control window classes commonly used in dialogs, and describes how to 
use them and how they “talk back” to their parent window. It also covers the 
particular type of control window called a static window. The remaining chap¬ 
ters in this part introduce and give examples of interacting with other control 
window classes. 

The reason for the wide variety of control window classes is simple: When 
creating dialogs, you want to make it impossible for users to do something 
wrong. If you have an entry field that will accept only numeric data, don’t let 
users type in a string and then tell them they’ve made a mistake. 
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Instead, prevent them from typing in nonnumeric characters in the first 
place. You could even put up a spin button that restricts entries not only to 
numbers, but also to numbers within an acceptable range. In this way, the 
wide variety of controls available helps you to create a better interface. 


A Different Kind of Application 
Framework 


For these discussions we are going to work with a completely new kind of 
application framework—one that creates not a window, but a dialog 7 


It isn’t common for the main window of an application to be a dialog, but that 
is not because it is difficult to do. (A WPS application might be only an object 
icon on the Desktop and a settings notebook, but the settings notebook 
doesn’t really count as a main window.) 



Dialogs and windows are very closely related, and can be used in similar 
ways. For example, a window could contain controls, and respond to the 
messages that those controls generate. A dialog could contain a blank client 
window area alongside its controls, if it had any. 


A good example of this might be a stock market program, where the client 
window area shows the prices of stocks as they change, and the dialog con¬ 
trols allow the user to make choices about when to buy and sell. 


Then the question becomes: Is the dialog really still a dialog? The answer is: 
It doesn’t matter. From a programming standpoint, we’ll call it a dialog if it is 
an instance of the WC_DIALOG class, regardless of how the user views it or 
what purpose it serves. 



For our purposes, creating a dialog window instead of a typical client window 
keeps us from having to devote any code to painting the window. (A dialog, 
you may have noticed, keeps its entire area filled with a certain color, and 
allows the controls to draw themselves on its space.) 

Keep in mind that the controls don’t care one way or another—they don’t 
even know whether they have a window or a dialog for an owner. So the dis¬ 
cussion of controls really doesn’t change, regardless of their context. 


Here’s the new framework: 


#define INCL_GPI 
^define INCL_WIN 
^include <os2.h> 
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^include "controll.h" 

/* ClientWndProc is a dialog procedure */ 

MRESULT EXPENTRY ClientWndProc(HWND, ULONG, MPARAM, MPARAM); 


int main 

(void) 



{ 

HAB 

hab; 

/* anchor block handle 

*/ 

HMQ 

hmq; 

/* message queue handle 

*/ 

HWND 

hwndFrame; 

/* handles to windows 

*/ 

QMSG 

qmsg; 

/* message 

*/ 

char 

szClassName[] = 

"Control Testing Program I"; 


BOOL 

fail = FALSE; 




SWCNTRL sw; 

hab = Winlnitialize(0); 

hmq = WinCreateMsgQueue(hab, 0); 

i f (!WinRegisterClass(hab, szClassName, ClientWndProc, 
CS_SIZEREDRAW, 0)) 
fail = TRUE; 

hwndFrame = WinLoadDlg(HWND_DESKTOP, HWND_DESKTOP, 

ClientWndProc, 0, C0NTR0L1PR0GRAMID, NULL); 

memset(&sw, 0, sizeof(sw)); 
sw.hwnd = hwndFrame; 

WinAddSwitchEntry(&sw); 

if ((fail ) || (hab==NULLHANDLE) || 

(hmq==NULLHANDLE) || (hwndFrame==NULLHANDLE)) 

WinMessageBox(HWND_DESKTOP, HWND_DESKTOP, 

"Unable to initialize application.", "ERROR!", 
0, MB_CANCEL | MB_ERR0R); 

el se 

while (WinGetMsg(hab, &qmsg, 0, 0, 0)) 

WinDispatchMsg(hab, &qmsg); 


Wi nDestroyWindow(hwndFrame); 
WinDestroyMsgQueue(hmq); 
WinTerminate(hab) ; 
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return 0; 
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MRESULT EXPENTRY ClientWndProc(HWND hwnd, ULONG msg, MPARAM mpl, 
MPARAM mp2) 

{ 

/*event handler*/ 
switch(msg) { 

case WM_CL0SE: 

WinPostMsg(hwnd, WM_QUIT, 0,0); 
return 0; 

} 

return WinDefD1gProc(hwnd, msg, mpl, mp2); 

} 



Unlike a WinDefWindowProc, when a WinDefDlgProc receives a WM_CLOSE 
message, it does not create a WM_QUIT message. As a result, the dialog will 
close, but not end the message loop. 

This will tie up the .EXE file and make it impossible for you to continue to 
work on the program without either rebooting or using a special utility to kill 
the process. 



Even though 1 have removed the “Save your work?” verification steps from 
the preceding application framework, the same code could be used with this 
dialog. 

Typically, however, a dialog operates on one of two principles: 


I u* Unless the user presses OK (or an equivalent), the dialog is considered 
to be canceled, regardless of how the user signals the cancellation 
(whether by pressing Alt+F4 or by shutting down the system). This 
would be common for a modal dialog. 

is* The changes the user makes take effect immediately, so the work is 
saved as the user goes along. This is the approach commonly taken by 
modal dialogs such as the settings notebook. « 

In order to make the program work, you need to create a dialog in the dialog 
editor—a plain one will do nicely—with an ID of CONTROL 1PROGRAMID. 
When you save this as CONTROL1, the dialog editor creates a CONTROL1.H 
file as well as a DIALOG.DLG file. 


You’ll still want to create an .RC file, although for now it will contain only one line: 

RCINCLUDE control 1.dlg 

Now you should be able to run the program, which will create a plain dialog 
as the main window of the application. 
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The Task List 

Although I don't want to go into great detail 
about the Task List, dialogs are not automati¬ 
cally added to the Task List by OS/2. Usually 
this is acceptable, but in a case like CON- 
TR0L1.C, where the only window is a dialog 
window, we'll want to add our dialog to the 
Task List. 

This is done with the following four lines of 
code in C0NTR0L1.C: 


and the dialog 

SWCNTRL sw; 

memset(&sw, 0, sizeof(sw)); 
sw.hwnd = hwndFrame; 
WinAddSwitchEntry(&sw); 

The SWCNTRL structure has a number of 
fields, but for adding a main window to the 
Task List, you need only zero out all the fields 
(as with memset), setthe SWCNTRL's hwnd to 
the frame window, and call WinAddSwitchEn- 
try with the address of SWCNTRL structure. 



Strictly speaking, the dialog created here is a modeless dialog, although since 
the application has no other windows, this is a pointless observation. After 
all, if the dialog can’t limit access to application services, it can’t functionally 
be modal. 


The Window Classes 


From here we’ll add various controls to this dialog, both from the resource 
editor and from our code. To do this, we’ll look at the WinCreateWindow 
function, and use the WC_* defines that describe each of the window classes. 

The window class defines (from OS2.H) are: 


WC_BUTT0N 
WC_FRAME 
WC_N0TEB00K 
WC_STATIC 


WC_C0MB0B0X 

WC_LISTBOX 

WC_SCROLLBAR 

WC_TITLEBAR 


WC_C0NTAINER 
WC_MENU 
WC_S LIDER 
WC_VALUESET 


WC_ENTRYFIELD 
WC_MLE 

WC_SPINBUTTON 


Of these, WC.FRAME, WC.MENU, WC_SCROLLBAR, and WCTITLEBAR have 
already been covered, and WC_CONTAINER and WC_NOTEBOOK are covered 
in Part V of this book. The rest of this part concerns itself with the remaining 
nine classes. 


This chapter alternates between describing aspects of control windows and 
describing how those aspects come into play in the static window class in 
particular. 
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Adding a window class to a dialog by using the dialog editor is simplicity 
itself. Simply click the mouse on the window class that you want to add, then 
click it on the dialog where you want the class to go. (Alternatively, you can 
select the control from the window.) 


Don't Give Me Any Static! 

A static control is a control that, in essence, does nothing. It can be informa¬ 
tional or just a decoration. It is called static because it doesn’t respond to 
user events, not because it can’t change. Static controls are a good place to 
start learning about controls because they are simple. 


In truth, there is only one static class, but it has many styles, which might 
make it seem like a very different control from one instance to the next. If you 
start your resource editor, you might see six controls that are just different 
styles of the WC_STATIC class: text, group box, icon, bitmap, rectangle, and 
frame. 



Resource editor is a generic term for any program that allows you to interac¬ 
tively manipulate resource file items. Dialog Editor and Resource Workshop 
are the names of specific resource editors. 


To use a static control in your dialog, all you do is place the control on the 
dialog. Each of the static styles has a number of options you can set. (In the 
Dialog Editor you can find these by selecting Styles from the Edit menu.) 


To use a text control, you need to specify the text, and for rectangle and 
frame controls, you need to specify the shading (half-tone or not) and color 
(foreground and background) that you want to use. 


Adding icons and bitmaps is a little less intuitive: You must assign an appro¬ 
priate resource ID so that the dialog can display the bitmap that you want. 


In general, you take the following steps to add and activate a bitmap or an 
icon control to your dialog: 

1. Add the bitmap or icon control to the dialog, just as you would any 
other control, appropriately located and sized. 

2. Assign a number or a symbol (or both) that will serve as the ID for the 
control, as you would for any control. 

3. Assign a number that will serve as an identification for the bitmap (not 
for the static control, but for the actual bitmap resource). The Dialog 
Editor program will not let you use a symbol here, but another resource 
editor might. (Alternatively, you could give the control the same ID num- 
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4. ber as the bitmap resource, but that could get confusing.) In fact, some 
resource editors might let you design the bitmap or icon on the spot. 

5. Save the dialog. If you’ve used a symbol for the bitmap, the editor will 
also make sure that the symbol is added to the appropriate .H file. 

6. Add a line to the .RC file for the project to define a bitmap using the 
appropriate symbol and the .BMP filename. (This was covered in Chap¬ 
ter 8, remember?) Adding this information is mandatory for the Dialog 
Editor, but may be unnecessary for other resource editors. 

7. Compile and integrate the .RC file with the .EXE file. 

To try this out, invoke your dialog editor, load up the CONTROL1 resource 
file and add a bitmap control. (The Dialog Editor will show this as a globe, 
but the globe will not appear in the dialog of your running program.) 

Identify the bitmap resource as number 1000. The top-most entry field of the 
dialog will contain some default number, which you’ll replace with 1000. 
Assign the static control the symbol of CID_BOXBITMAP and give the control 
an ID of 100. Save the dialog. 

Now change the CONTROL1.RC file by adding a couple of lines before the 
RCINCLUDE: 


//include <os2.h> 

BITMAP 1000 box.bmp 


RCINCLUDE control 1.dlg 


This short listing should make evident the distinction between the bitmap’s 
ID and the static window’s ID. The bitmap is a resource in its own right, with 
an ID of 1000. The static window has an ID and a symbolic identifier that bear 
no relation to the bitmap’s ID. 

You could access the box bitmap by its resource number (1000) and by using 
GpiLoadBitmap to load it. 



hbmp = GpiLoadBitmap(hps, 0, 1000, rcl.xRight,rcl.yTop); 

See Chapter 8, “Bitmaps, Icons, and Pointers,” for more details on loading 
and drawing bitmaps. 


Meanwhile, you could do stuff with the static control based on its ID, indepen¬ 
dently of the box bitmap. For example, 


hstatic = WinWindowFromlD(hwnd, CID_B0XBITMAP); 
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You could then send messages to the hstatic window to make it change its 
bitmap, or even change its style from bitmap to text. 


Control Window Styles 

General window styles were covered in Chapter 3, “The Basic Application 
Framework Explained!” You can use Table 3-1 from that chapter to set styles 
for your controls, although obviously they won’t all make sense. WS_ANI- 
MATE, for example, isn’t going to make your control explode onto the dialog 
and generate the system sound. (Can you imagine a dialog where all the con¬ 
trols did that?) 

Table 11-1 is the short form of Table 3-1 showing the styles you might com¬ 
monly set for a control. 


Table 11-1 Common Control Window Styles 

Style 

Meaning 

WS_CL1PSIBLINGS 

Don't draw in sibling windows' areas. 

WS_DISABLED 

Don't reactto keyboard or mouse input. 

WSJ3R0UP 

Indicates the first member of a group. (See Chapter 12.) 

WS_PARENTCLIP 

Don't draw outside the parent. 

WS_SYNCPAINT 

Forces all painting messages to be handled immediately. 

WS_TABSTOP 

Selectable by using the Tab key. (See Chapter 12.) 

WS_VISIBLE 

Be visible. 


In addition to these window styles, each control window has a set of styles all 
its own. These sets are part of the same bit mask, so you can set the style for 
a window this way: 

options = WS_WINDOWOPTIONS | CS_C0NTR0L0PTI0NS; 

These options can be used with WinCreateWindow to create control windows 
programmatically. Most often, however, you’ll use the dialog editor, and set 
the appropriate styles from within it. 
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Static Styles 

The static window class has a fairly large number of options to choose from. I 
have divided them into two sets here, one for the type of static window 
(Table 11-2), and the other for the presentation options of the static window 
(Table 11-3). 


Table 11-2 Types of Static Controls 

Style 

Description 

SS_BITMAP 

Displays a bitmap. 

SS_GR0UPB0X 

Draws a box. Used to collect other controls into a single unit. 

SSJCON 

Displays an icon. 

SS.SYSICON 

Displays a system icon. 

SS_TEXT 

Displays text. 

Always use one option from Table 11-2 when creating a static window style to 
determine the type of the window. You can additionally use one option from 

Table 11-3. 



Table 11-3 Presentation Options for Static Controls 


Style 

Description 

SS_AUTOSIZE 

Changes the static control's size to fit the contents. 

SS_BGNDFRAME 

Displays a box with a frame, with the frame in the 
background color. 

SS_BGNDRECT 

Displays a rectangle filled with the background color. 

SS_FGNDFRAME 

Displays a box with a frame, with the frame in the 
foreground color. 

SS_FGNDRECT 

Displays a rectangle filled with the foreground color. 

SS_HALFTONEFRAME 

Displays a rectangle with a half-tone frame. 

SS_HALFTONERECT 

Displays a rectangle filled with half-tone color (dimmer). 



Every control has a number of style options. These are always indicated by a 
prefix where the first letter (or letters) represents the control class, and the 
last letter is an S for style. 
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So the static control styles are SS_*, for static styles. 

SS_AUTOSIZE makes the most sense for icons, bitmaps, and text. The remain¬ 
ing options would be used to set group boxes, rectangles, and frames. 

SS_AUTOSIZE works only when the control is first created, and so is useless 
when using the Dialog Editor. Other resource editors are more responsive. 



Control Window data 

The purpose of most controls is to allow the user to communicate some 
choice or input. As such, these window classes generally carry some data 
along with them to indicate what the user selection or input was. A typical 
control window will have a structure associated with it that is used to com¬ 
municate the pertinent information. This same structure can be used with 
WinCreateWindow to create a control. 

Static windows allow no choices and therefore have no data structure associ¬ 
ated with them, so they are an exception to this rule. 

We won’t look at control window data in this book, as it is far easier to simply 
rely on the dialog editor to create controls, and to use messages to fetch the 
user input. 


Control Windou! Messages 

There are two ways to interact programmatically with a control window. The 
first is to use a regular Win*-type call that is set up for a specific purpose. 
Examples of this would be WinSetWindowText and WinQueryWindowText, 
which we saw in Chapter 10. 

WinSetWindowText changes the passed window’s text to whatever is passed 
in the second parameter. The actual effect of this depends on the window 
class. For static text, it’s pretty obvious—the text changes. You might write 
something like the following to create a progress indicator: 

case WM_PR0GRESS: 

sprintf(newtext, "Progess: %d", SH0RT1FR0MMP(mpl)); 

WinSetWindowText( 

WinWindowFromID(hwnd , SID_PROGIND), 
newtext); 
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WinSendMsg(hwnd, WM_PAINT, 0, 0); 
return 0; 


In this example, WM_PROGRESS is a message sent by a different thread run¬ 
ning in your program that passes some value indicating progress in mpl. 
SID_PROGIND is a static text control, of course. 

In the case of the frame window class, on the other hand, WinSetWindowText 
changes the title. For an entry field, the input text changes. For a button, the 
caption changes. And so on. 

The second way to interact programmatically with a control window is to send 
a message to the window to perform some action. In this case, WinSendMsg is 
used and the commands passed are varied to create different effects. 

Most control windows have their own messages. WC_STATIC has only two 
unique messages that it responds to: 

SM_QUERYHANDLE Returns the handle of the bitmap or icon. 

SM_SETHANDLE Sets the handle of the bitmap or icon. 

far The messages that are unique to a particular window class are indicated by a 
prefix in which the first few letters represent the class, and the last letter is 
ffojl an for messages. 

So, static window messages are designated with SM_*. 

You can use SM_QUERYHANDLE to find out if a static is displaying a bitmap 
or an icon. (WinSendMessage will return the handle to the bitmap or icon, or 
zero if there isn’t a handle.) 

SM_SETHANDLE, on the other hand, allows you to pass a bitmap or icon han¬ 
dle as mpl to change the current appearance of the static. 

Most control windows also respond differently to standard WM_* messages. 
WC_STATIC, for example, responds to these three messages in its own way: 

WM_MATCHMNEMONIC Does the static match the char (passed as 

the first short of mpl)? 

WM_QUERYWINDOWPARAMS Stores the current presentation 

parameters in the PWNDPARAMS 
structure (passed as mpl). 

WM_SETWINDOWPARAMS Sets the current presentation parameters 

to the PWNDPARAMS structure (passed 
as mpl). 
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Two messages that all dialog controls handle in essentially the same way are 
WM_QUERYWINDOWPARAMS and WM_SETWINDOWPARAMS. In order to 
understand what these messages do, you need to know what presentation 
parameters are. 

When OS/2 draws a button, a menu, or any kind of window for that matter, it 
needs to draw the item in a specific color. Programmers often like to cus¬ 
tomize colors and fonts for their applications, but if you have ten buttons, 
you wouldn’t really want to call a WinSetColor type method for each button, 
would you? 

Instead, there are about four dozen defines for the foreground color, the 
background color, menu items, button fonts, and so on. Four dozen may 
seem like a lot, but there have to be separate colors for the different states of 
items as well. So there isn’t just one entry for menus, there’s an entry for a 
menu item, for a highlighted menu item, for a disabled menu item, and so on. 

Fortunately, you don’t have to deal with all the colors as a unit. You can set 
exactly one color for a specific entry in the presentation space and keep the 
other entries at their default values. 

In truth, I’ve noticed very few OS/2 applications that actually change the 
user’s default color selections. Doing so is a rather involved process that 
requires setting up several structures. We won’t get sidetracked with this 
process here. 

Control Window Notifications: 

Why Don't \[ou Ei/er tail Back) 

Most windows give some kind of notification when a significant event occurs. 
Significant here means anything the dialog procedure might be expected to 
react to. These are sometimes called callbacks, because the owning window 
passes messages to the control windows, and the control windows respond 
with information about the effects of those messages. 

Technically, these are called notification messages, but I’ll usually refer to 
them as callbacks. 

We’ve seen several callbacks already, believe it or not. In Chapter 6, we used 
the scroll bar window class notifications returned to our main window to 
determine how to scroll our data. 
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In the last chapter, when experimenting with buttons, we acted on the Cause 
button’s notification that it had been pressed by toggling the enabled state of 
the Effect button. Button notifications will be covered in detail in the next 
chapter, but we can relate that cause-effect program to this discussion by 
observing that a button creates a WM_COMMAND notification. 

One of the more common callbacks that a control will generate is the 
WM_CONTROL message. This is a kind of catch-all that passes both the con¬ 
trol ID (in the first short of mpl) and a notification code (in the second short 
of mp2) to indicate that some event has occurred in the control. (A check 
button, for example, would generate one of these messages when clicked or 
double-clicked.) 

Knowing what notifications are possible can make it easier to set up a 
responsive dialog. For example, knowing that an entry field sends a message 
when it is changed can make verifying the data in an entry field very easy. 
(Simply check for the message in the dialog message handling procedure, 
and correct the entry field if an invalid character was entered.) 

The WC_STATIC window class has no notifications. That’s why it’s static, 
really—nothing ever happens to it. 

w Callbacks are always designated with a prefix, where the first letter (or let- 
ters) represents the control class and the last letter is an N, for notification . 

//"the static control had any callbacks, they would be designated with SN_*. 


JaB Order 

Tab order is the order in which controls get the focus as the user presses the 
Tab key. Generally a dialog’s tab order should follow cultural norms. 

In other words, for English and most Western languages, the Tab key should 
move the focus from left to right, top to bottom. 

The logic is that the Tab key should take users where they expect to go. For 
other cultures, a different standard might be used. For Hebrew, you might 
have the tab order move from right to left, for example. Other languages and 
cultures would dictate a top-to-bottom orientation. 

Some users never use the keyboard if the mouse is available, and thus never 
notice tab order. But neglecting tab order is a good way to tick off us key- 
board-clicking types. (Watcom’s IDE and IBM’s VisualAge IDE both have 
dialogs where the focus jumps around when the Tab key is pressed. This cre¬ 
ates a bit of extra work and annoys me to no end!) 
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Resource editors create a tab order according to when you placed a control, 
not where you placed it. In other words, the last control you place will be last 
in tab order, regardless of whether it is immediately to the left of the first 
control, in the middle of the form, or wherever. 

Fortunately, resource editors all have some other way to set the order of the 
controls. In the Dialog Editor, for example, the Arrange menu contains an 
item called Order Groups that brings up a dialog to let you change the tab 
order. (Groups are covered in the next chapter.) 

A static control focuses the next control in tab order if the user presses its 
mnemonic key. If a text static “Name” is followed by an entry field, the user 
can get to the entry field by pressing Alt+N. 


Dial 1‘800‘Win* to Ease 
dialog Handling 

The PM API contains seven functions that can make handling dialogs easier 
than using WinWindowFromID in conjunction with another API call: 

General Form: BOOL WinEnableControl(HWND hdlg, USHORT id, BOOL 
enable); 

General Form: BOOL WinQueryDlgltemShort(HWND hdlg, ULONG id, PSHORT 
result, BOOL sign); 

General Form: ULONG WinQueryDlgItemText(HWND hdlg, ULONG id, LONG 
bufsize, PSZ text) ; 

General Form: ULONG WinQueryDlgITemTextLength(HWND hdlg, ULONG id); 

General Form: MRESULT WinSendDlgltemMsg(HWND hdlg, ULONG id, ULONG 
msg, MPARAM mpl, MPARAM mp2); 

General Form: BOOL WinSetDlgltemShortCHWND hdlg, ULONG id, USHORT 
value, BOOL signed); 

General Form: BOOL WinSetDlgltemText(HWND hdlg, ULONG id, PSZ 
text); 

WinEnableControl sets the enabled state of the control. A control that is not 
enabled will not respond to user input. 

WinQueryDlgltemShort takes the text value of a control and returns that 
value after it has been converted into a number in the signed short range 
(-32768 to 32767). WinSetDlgltemShort takes an integer value and sets the 
text of the dialog item to be that integer value. 
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WinQueryDlgltemTextLength returns the size of the buffer needed to hold the 
text currently in a control (less the null terminator). After you allocate a 
buffer of the appropriate size, you can call WinQueryDlgltemText to get the 
text. Finally, you can set the item’s text through WinSetDlgltemText. 

It’s an odd assortment of calls, really, and I can’t tell you why these particular 
functions were singled out, since the same effects can be created through 
WinSendMsg calls. It’s possible that the seven calls were functions that 
0S/2’s designers found themselves needing often. In particular, as you’ll see 
in the upcoming chapters, WinSendDlgltemMsg is a lot handier to use than 
WinWindowFromID and WinSendMsg. 

I also can’t tell you for certain why dialog IDs are sometimes specified with 
USHORTs and other times with ULONGs. But it’s probably not a coincidence 
that the total bit size of all the parameters for these calls is always evenly 
divisible by 32. 


Conclusion 

None of this stuff is difficult to understand, once you grasp the concept that 
controls are windows of their own with their own message handlers and so 
forth. Programming becomes simply a matter of notification and handling. 

Controls are basically easy to work with, though they sometimes require a lot 
of typing. The controls covered in the upcoming chapters get progressively 
more complex to manage, although they’re not really difficult—just a bit 
more involved than WC_STATIC. 




Chapter 12 

Buttons 


h This Chapter 
Pushbuttons and their styles 
Groups of buttons 

Radio buttons, check boxes, and more 


Jf^uttons are symbolic of power. When we press a button, we expect 
something to happen. When we are frightened about global warfare, 
we’re worried about what madman might have his finger on The Button. But¬ 
tons are not for the timid. 


Even in computer programs, buttons represent considerable power: We have 
delete buttons, reset buttons, apply buttons. 

Generally speaking, when we think of buttons we usually think of pushbut¬ 
tons. However, in OS/2 the WC_BUTTON class has several styles, including 
the check box and radio button styles. (On some graphical systems, menu 
items are considered buttons because they are functionally so similar to 
pushbuttons or check boxes.) 


Ike WCJMTTON Class 

Using the basic application framework from the previous chapter (CON- 
TROL1.C), create a new program called BUTTONS and a new dialog. On this 
dialog place two pushbuttons, a group box, three radio buttons inside the 
group box, and a check box outside of the group box. 

Figure 12-1 illustrates the three basic styles of pushbuttons, which can be fur¬ 
ther broken down by the button style constants shown in Table 12-1. 
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Name Description 

BS_3STATE A check box that has three possible states: checked, 

unchecked, or half-toned. (You must set the state.) 

BS_AUT03STATE A three-state check box. (Sets its own state.) 

BS_AUTOCHECKBOX A check box. (Sets its own state.) 

BS_AUT0RADI0BUTT0N A radio button. (Sets its own state and the state of 

others in its group.) 

BS_CHECKBOX A check box. (You must set the checked state.) 

BS_PUSHBUTTON The usual pushbutton (for example, OK or Cancel). 

BS_RADI0BUTT0N A radio button. (You must set its state and un-set the 

state of others in its group.) 

BSJJSERBUTTON A button that you control the painting of based on its 

selection state. 


This table is probably needlessly complicated by the presence of BS_CHECK- 
BOX, BS_RADIOBUTTON, and BS_3STATE. These are button styles that notify 
the owning window that they have been pressed but that require the owning 
window to set their state upon being notified. 

In other words, if the user clicked the mouse on a BS_CHECKBOX style but¬ 
ton, the check box wouldn’t change! It would just notify the window that the 
event had occurred. So, too, with BS_RADIOBUTTON and BS_3STATE. 

I’m sure there’s something terribly clever that can be done with this level of 
control, but for the purposes of this book, we’ll stick with the AUTO style but- 
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tons. (If you want the extra work, you can use what you learn here with the 
nonautomatic styles.) 

BS_USERBUTTON is interesting in that you can put one of these on your dia¬ 
log and, in response to callbacks from the button, completely control the 
appearance of the button when it is pressed, when it is released, when it is 
highlighted, and when it is disabled. 

Any of these basic styles may also have the BS_NOPOINTERFOCUS option 
set. With this option set, the button will not select itself when the mouse is 
used to click it. 

This can be handy in data entry situations: Imagine a data entry form that 
contained controls for name and address, and that had an Add button. If 
users wanted to enter an entire family’s data, they might do so by changing 
only the first name entry field and clicking on the Add button. If the button 
selects itself, they would then have to tab all the way back to the first name 
entry field (or use the mouse). If the button doesn’t select itself, the first 
name field stays focused, and saves wear and tear on the carpal tunnels. 


Pushbuttons 

Besides the options specified in Table 12-1, pushbuttons also allow the 
options in Table 12-2 to be set. Note that the pushbutton is the only button 
style that can display graphics. 


Table 12-2 Pushbutton Styles 

Name 

Description 

BS_BITMAP 

Pushbutton displays bitmap instead of text. 

BS_DEFAULT 

Pushbutton is the default (clicks itself when Enter is 
pressed). 

BS_HELP 

Pushbutton generates a WM_HELP command. 

BSJCON 

Pushbutton displays icon instead of text. 

BSJVIINIICON 

Pushbutton displays a mini icon. 

BS_N0B0RDER 

Pushbutton has no border around it. 

BS_SYSCOMMAND 

Pushbutton creates a WM_SYSCOMMAND command. 

BS_TEXT 

Pushbutton displays text. Used in conjunction with 

BS_BITMAP, BSJCON, or BSJVIINIICON, allows button to 
display both text and a graphic. 
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Pushbutton specifics 

When you put a pushbutton on a dialog, remember that a pushbutton, by 
default, generates a WM_COMMAND message, and a WM_COMMAND mes¬ 
sage will close the dialog. So, if you don’t want the dialog to go away when 
the button is pushed, you have to intercept the generated command and 
return 0: 

case WM_C0MMAND: 
switch(SH0RT1FROMMP(mpl)) { 
case PID_S0MEBUTT0N: 

/* code for PID_S0MEBUTT0N */ 
return 0; 


This is not usually a big deal, since even if you don’t want the dialog to be 
closed by a button, you still want the button to perform some action. You 
would put the code in the commented area shown, and make certain the 
event did not pass through to WinDefDlgProc. 

You can change the effect of pushing the button (without coding anything) 
by setting the BS.HELP or the BSJSYSCOMMAND option. A button that has 
the BSJHELP or BS_SYSCOMMAND option set will not close the dialog and 
will generate a WM_HELP or WM_SYSCOMMAND instead of a WM_COM- 
MAND message. 

You can send one message specifically to the pushbutton style of the 
WC_BUTTON class. BM_SETDEFAULT sent with TRUE as mpl will make the 
receiving button the default for the dialog. 


Group Awareness 

The other two styles of buttons (radio buttons and check boxes) usually 
appear in clusters called groups. A group implies a connection between con¬ 
trols and, in the case of radio buttons, has an actual behavioral connection. 

In a group of radio buttons, like those we set up for the BUTTONS program, 
any time one is selected the others in the group should be deselected. You 
can send a single message, BM_QUERYCHECKINDEX, to any radio button in a 
group and it will return the index of the button currently checked. 
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In order for this feature to work properly, you must contain your radio boxes 
within groups. In the Dialog Editor, you do this by first placing a group box, 
and then by placing radio buttons on top of it. 

If you make your dialog like the one shown in Figure 12-1, you can experience 
first hand the oddities created by having radio buttons that are not part of a 
group. (I’ll bet you can’t wait!) 


You don’t need a group box, strictly speaking, if you set the radio button’s 
style to WS_GROUP (or click the group check box in the Styles dialog for a 
control). A WS_GROUP control indicates the first item in a group of controls. 
The group includes every control after that item (in tab order) until another 
WS_GROUP style window is encountered. 


Groups have another use besides selecting and deselecting radio button set¬ 
tings: A group of controls can be selected using the cursor. To move from 
group to group with the keyboard, the Tab key must be used. 


This index returned by BM_QUERYCHECK INDEX is zero-based, so for the 
middle group of radio buttons in Figure 12-1, if Planes were selected, 0 would 
be returned. If Trains were selected, 1 would be returned. If Cars were 
selected, 2 would be returned. -1 might also be returned to indicate that no 
button is currently selected. 


In a group of check boxes, the items are usually conceptually related, but 
have no programmatic connection. You might think that you could query a 
group of check boxes and get back a bit mask with each bit indicating which 
check boxes had been set, but you can’t, so forget about it! You must query 
each check box individually. 



The BS_CHECKBOX and BS_RADIOBUTTON style buttons won’t set them¬ 
selves. Instead, like radio buttons, they’ll send you a WM_CONTROL message 
and you’ll have to respond to the message by setting them. (You’ll see how 
to do this in the next section.) That’s why you will generally want to use the 
BS.AUTOCHECKBOX and BS_AUTORADIOBUTTON styles. 


Radio Button and Check Box Specifics 

Radio buttons can be created using the BS_NOCURSORSELECT style, which 
means that a user cursoring through a group of radio buttons does not 
change the selected radio button. (The change must be initiated using the 
spacebar. Mouse selection is unaffected by this option.) 

The state of a particular radio button or check box can be queried through 
WinQueryButtonCheckstate. 
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General Form: USHORT WinQueryButtonCheckstate(HWND hwnd, USHORT 
ID); 

As Used: if (WinQueryButtonCheckstatelhwnd, RID_PLANES)) 

WinMessageBoxt HWND_DESKTOP, hwnd, 

"Take a piane!", "", 0,0); 

The function returns TRUE if the button is checked, and FALSE otherwise. 

If you’re using C or another case-sensitive language, watch out for this API 
call: It’s WinQueryButtonCheckstate, with a small s for state, as if one spelled 
Checkstate as all one word. 

BM_QUERYCHECK and BM_SETCHECK can be used with both radio buttons 
and check boxes. Send TRUE or FALSE, respectively, as the mpl for 
BM_SETCHECK in order to check or un-check a button. 

For a three-state check box, BM_QUERYCHECK can return more than 0 (not 
checked) or 1 (checked). It can also return 2, which signifies an “undeter¬ 
mined” state. (This is just a half-tone gray filling the box.) 

BM_QUERYCHECKINDEX, as mentioned, can be used as a short-cut to deter¬ 
mine which one in a group of radio buttons is set. 

Radio buttons and check boxes generate WM_CONTROL messages when 
clicked. The first short of mpl will be the button’s ID. The second short will 
be a notification code, telling you what event occurred in the button or box 
(either BN_CLICKED or BN_DBLCLICKED). mp2 will be the handle of the but¬ 
ton or box that was pressed. 


General Button Stuff 

All button windows may be sent BM_QUERYHILITE and BM_SETHILITE, to 
query or to set the highlighted state. What’s the highlighted state, you ask? 
Good question! 

If you look back at Figure 12-1, you’ll see that the Hilite button appears to be 
pressed. This is what the highlighted state for a pushbutton looks like. 

A button drawn in a highlighted state looks like it is being pressed. When you 
click the mouse on a pushbutton, it appears to go down, right? Well, you can 
set a button to always look that way. And you can do this with radio buttons 
and check boxes, too. 
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It’s downright odd, actually, but again, a lot of OS/2 stuff is designed for flexi¬ 
bility, and just because the usefulness of something isn’t apparent doesn’t 
mean that isn’t real. 

For example, you might use BM_SETHILITE if the user pressed a button in a 
dialog that started a long action. You could force the button to appear to 
remain pressed for the duration of the action (and even disable it in conjunc¬ 
tion with setting the highlighted state). 


Conclusion 

Buttons are useful controls, and fortunately are easy to understand and use. 
Entry fields are up next, and they are even easier, in some ways. 
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Entry Fields 


In This Chapter 
All about entry fields 
A bit about data validation 


B wo controls allow the user to type in text from the keyboard: the entry 
m field and the multiline editor (MLE). 

These types of controls are very common, especially the entry field, but if 
you can, avoid using them. You won’t always be able to, and sometimes you’ll 
find it is too much work to avoid them. 

You should try to avoid using them because they encourage freedom, and 
freedom in a data entry form can be a bad thing. If a form has a field for 
Name, an entry field is unavoidable. At the same time, you should realize that 
a user can type anything into that entry field, such as a phone number, a ZIP 
code or an address. 


This means that in many cases, using an entry field requires writing some 
code to validate the user’s input and informing the user or correcting the 
input if it is wrong. (Prevention is better than cure in programming, too.) 

For this chapter, copy over the basic dialog code again from Chapter 11, and 
create the form shown in Figure 13-1. 


Figure 13-1: 
The ENTRY 
program's 
dialog. 
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As always, I’ve included code samples that you can use to test how entry 
fields work. 


Entry Fields Basics 

Entry fields are controls that allow exactly one line of text to be entered. The 
deceptive thing about entry fields for a lot of users is that often after typing a 
line, a user has a strong desire to press Enter. The entry field itself does noth¬ 
ing when Enter is pressed, but the default button for the dialog is triggered 
instead, which can have alarming consequences. 

Entry fields have a wide variety of styles, but fortunately only one basic type 
(unlike buttons and statics), and all the options apply to that type. 

Table 13-1 shows the available entry field control styles. 


Table 13-1 Entry Field Styles 

Style 

Description 

ES_LEFT 

Displays left-justified text 

ES_RIGHT 

Displays right-justified text 

ES_CENTER 

Displays centered text. 

ES_AUTOSIZE 

Entry field is sized to ensure that the text fits 

ES_AUT0SCR0LL 

Entry field scrolls when the user cursors past the end 

ESJV1ARGIN 

Creates a border 

ES_READONLY 

Entry field allows no input 

ESJJNREADABLE 

Entry field shows no input 

ES_COMMAIMD 

Use text in entry field as help index 

ES_AUTOTAB 

Tab to next control when field is full 


(There are also four special options used to handle double-byte character 
encoding schemes (DBCS). This book doesn’t cover DBCS, so these special 
options have been left out.) 

Most of the options shown are self-explanatory, but them, the best way to 
learn what purpose they serve is to try them out. 
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A few of the less obvious options are: 


u* ES_UNREADABLE, which displays asterisks instead of the user’s text (for 
password masking). 

v* ES_AUTOSCROLL, which if it isn’t set, allows users to type past the right 
boundary of the entry field. (In other words, the cursor goes off screen 
and users can no longer see what’s being typed). 

v* ES_COMMAND, which is actually a hook for the help system. 

is 0 ES_AUTOSIZE, which sizes the control to match the text inside it. 



Actually, the ES_AUTOSIZE feature works only when the entry field is first 
created, and doesn’t work in the Dialog Editor, where you are manually resiz¬ 
ing the control anyway. 

It isn’t clear why the Dialog Editor allows you to set this option, m 


Sending, messages to entrg fields 

You may send a number of messages to an entry field, as shown in Table 13-2. 

All offsets to characters in entry fields are zero-based, just like C strings: A 
query will return a 0 to indicate the first character in a string, a 1 to indicate 
the second, and so on. 

The clipboard messages can be used if you want to allow the user to select a 
menu item that copies text to the clipboard (EM_COPY, EM_CUT), pastes 
text from the clipboard (EM_PASTE), or deletes the currently selected text 
(EM.CLEAR and EM_CUT). But the WC_ENTRYFIELD class will perform those 
functions automatically in response to the usual keys (Ctrl+Ins for copy, 
Ctrl+Del for cut, Shift+Ins for paste, and Del for clear). 

Also, although you can set the selected text manually using EM_SETSEL, the 
WC_ENTRYFIELD class responds automatically to the user who presses Shift 
and a cursor key by marking the text. 

So again, we see that messages sent to control windows are used for greater 
control and flexibility of a window, and not to provide standard behavior. 
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Table 13-2 Entry Field Messages 

Message 

Description 

EN_CLEAR 

Clear the selected text. 

EN_C0PY 

Copy the selected text to the clipboard. 

EN_CUT 

Cut the selected text to the clipboard. 

EN_PASTE 

Paste the text from the clipboard. 

EN_QUERYCHANGED 

Has the entry field been changed since the last 
EN_QUERYCHANGED message or 
WM_QUERYWINDOWPARAMS message? 

EN_QUERYFIRSTCHAR 

What is the position of the left-most character that is 
currently showing? 

EN_QUERYREADONLY 

Is the entry field read only? 

EN_QUERYSEL 

What are the offsets of the start and the end of the 
current selection? (Returned as two shorts.) 

EN_SETFIRSTCHAR 

Scroll so that the first character showing is the one at 
the offset indicated by mpl. 

EN_SETINSERTMODE 

Set insert mode on or off, depending on the value of the 
BOOL in mpl. 

EN_SETREADONLY 

Set the read-only style of the entry field on or off, 
depending on the value of the BOOL in mpl. 

EN_SETSEL 

Set the selected text to start and end at the offsets 
indicated by the two shorts in mpl. 

EN_SETTEXTLIMIT 

The entry field should allowthe userto enter no more 
than the number of characters indicated by mpl. 


Ironically, the Dialog Editor does not allow you to set the entry field text 
limit, so you’ll have to use EM_SETTEXTLIMIT any time you want more than 
the default 32 characters of space. 

I used the following line immediately after WinLoadDlg to set the text limit of 
the entry field shown in Figure 13-1: 

WinSendDlgItemMsg(hwndFrame, EF_TESTENTRY, EM_SETTEXTLIMIT, 
MPFROMSHORT(10), 0); 



Actually, it is possible to create an entry field with more than 32 characters of 
space in it, but to do so you must use the WinCreateStdWindow call and pass 
a special data structure to it that describes the particulars of the entry field 
construction. 
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Alternatively, you can use WinSetWindowParams, which also allows you to 
pass that data structure (as well as the presentation parameters for the 
object). 

Both of these techniques can be used with all the controls, but they involve 
considerably more work than using the Dialog Editor and sending a message 
to adjust as needed. 


Entr$$ field callbacks 

An entry field will notify its parent that something has happened to it by 
using the WM__CONTROL message. As always, the first short of mpl indicates 
the control ID, and the second contains a notification code. 

Unlike buttons, however, an entry field has a lot to report, as Table 13-3 
shows. 


Table 13-3 Entry Field Callbacks 

Notification 

Description 

EXCHANGE 

The contents have changed. Sent afterthe change has 
been shown on screen. 

EN_KILLFOCUS 

The entry field is about to lose the focus. 

ENJVIEMERROR 

You sent an EM_SETTEXTLIMIT message and the entry 
field was unable to allocate the requested memory. 

ENJDVERFLOW 

An attempt was made to insert more text into the field 
than the field allows. You can respond to this message by 
sending an EM_SETTEXTLIMIT message to give the field 
more space and returning TRUE. 

EN_SCR0LL 

The entry field is about to scroll. 

EN_SETFOCUS 

The entry field is about to receive the focus. 


As always, I’ve included code to show how some of these messages work, but 
basically remember that handling messages is handling messages: You field 
the ones that you’re interested in and ignore the ones that you don’t care 
about. 





Part III OS/2 Controls. 


^(OSfy, 



Data validation 


There are three basic approaches to data val¬ 
idation that are important to consider when 
building any dialog for any user interface. 

v* One kind of data validation is to put up a 
dialog, let users enter anything, and then 
when they are done fiddling with every¬ 
thing and press OK (or the equivalent), 
the program fetches all the data and 
pops up an error message if there are 
any mistakes. 

v* Another kind of data validation is to put 
up a dialog, and let users set a particular 
control to whatever value. However, 
when they press Tab or otherwise try to 
focus on a different control, the program 
checks the current control to make sure 
that its contents are valid, and doesn't 
allow the focus change to take place 
until the current control has a valid value. 
In an entry field, this is done by acting on 
the EN_KILLFOCUS message. 

\s* A third kind of data validation, probably 
the best, is simply to not allow users to 
set any control to an invalid value. If the 
field requires numbers, don't let users 


type letters. If the field requires a range 
of numbers from 1 to 10, don't let users 
type 11, and so on. This is done, ideally, 
with controls that allow themselves to be 
set only to particular values. With entry 
fields, this is done by intercepting every 
character typed when the entry field is 
focused, and by establishing whether the 
character would invalidate the entry field 
data. (Or you can validate immediately 
after the character is typed, as shown in 
the last codefragment.) 

Ideally, in this last type of data validation, the 
dialog pops up with a valid entry, so that it 
always contains valid data. That isn't always 
feasible, so sometimes a combination of 
methods is required. 

One good idea, for the last two approaches 
especially, is to disable the OK (or equivalent) 
button until the dialog is completely valid. 
Doing that with the first approach can be 
problematic since users can fill out the entire 
dialog and then find out that the OK button is 
disabled—this tells they that he made a mis¬ 
take, but it doesn'ttell themwhere. 


Here’s a sample of code you might use to prevent the entry field from having 
an invalid entry: 

case WM_C0NTR0L: 

switch(SH0RT2FROMMP(mpl)) { 
case EXCHANGE: 

WinQueryDlgltemText(hwnd, EF_TESTENTRY, 1000, str); 
oldstr = dlgstruct->testentry; 
dlgstruct->testentry = str; 

if (invalid(d1gstruct)) { /*"invalid" is your fn*/ 

WinSetDlgltemText(hwnd, EF_TESTENTRY, oldstr); 
dlgstruct->testentry = oldstr; 

1 

return 0; 
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Assume that dlgstruct contains all the information that the dialog queries, 
and that it starts off valid and is checked for validity any time a change is 
made, through your invalid function. (The dlgstruct pointer itself would be 
stored in the window words for the dialog.) 

Now in some cases, it’s better to catch the keypresses as they come in, and 
to avoid passing them to the entry field if they would cause the entry field’s 
data to become invalid. At other times, it may be easier for you to let the field 
be changed, and then change it back if it’s wrong. 

You could happily use entry fields without ever paying attention to these 
notifications, except for data validation. 


Conclusion 

Entry fields are largely unavoidable, at least given the current state of the art 
of designing data entry forms. However, you can make entry fields relatively 
easy to use by picking a good data validation scheme and by using them 
sparingly. 

You can also make them easier to use by displaying formatting characters 
that provide clues as to what kind of data is supposed to go into them. For 
example, you might use a static showing a $ next to an entry field that is 
meant to hold monetary amounts. 



Chapter 14 


List Boxes and Combo Boxes 


In This Chapter 

List boxes—the last (and first) word 
Combo boxes—working together 


KM/e can cover list boxes and combo boxes together because they are 
Ww conceptually very similar, and a combination box (the formal name 
for a combo box) is a combination of a list box and an entry field. (Hence the 
name.) 


As always, start up a new project using the CONTROL1.H framework and 
build the dialog shown in Figure 14-1. 


Figure 14-1: 
The 
LISTBOX 
dialog. 


Dialog Title 


Item 1 

j ! 1 

Item 5 
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Item 2 


Item A 



Item 3 


Item 3 



Item A 


Item 2 



Item 5 
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Item 1 
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The three boxes are defined as (from left to right) LID_MULT, LID_EXT, and 
LID_MULTEXT. The pushbuttons are called PID_QUERY and PID_SEARCH. 

Much of what applies to the WC_LISTBOX class also applies to the 
WC_COMBO class, so we’ll look at WC_LISTBOX first. 
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The List Box 

A list box is a box with a list in it, obviously, and the list is usually a number 
of text strings displayed to the user. Each item in a list box can have addi¬ 
tional data associated with it, too, which allows you to use the list box as a 
way of storing any kind of data object along with a text description of that 
object. 

A list box can have any of the styles described in Table 14-1. (As always, how¬ 
ever, certain combinations may not make sense.) 


Table 14-1 List Box Styles 

Style 

Description 

LS_H0RZSCR0LL 

Show horizontal scroll bar. 

LS_MULTIPLESEL 

Allow multiple discrete selection. 

LS_EXTENDEDSEL 

Allow multiple selection by swiping only. 

LS_OWNERDRAW 

The owning dialog draws the control. This is usually 
done to allow the list box to display more than text. 

LSJMOADJUSTPOS 

Don't adjust the height of the scroll bar to be an even 
multiple of the item height. 


Multiple selection allows the user to select noncontiguous items in the list 
box. With this option, a click (from the mouse or the spacebar) on an item 
selects it, and another click deselects it. The user may select items at random 
from anywhere in the list box. 



Extended selection allows the user to select contiguous items in the list box, 
by holding the primary button down and dragging the mouse across the list 
box, or by holding down the Shift key and moving the cursor up or down. If 
the user starts another selection after already having selected a group, the 
old selection is deselected. In other words, only one set of items, all right 
next to each other, may be selected. 

Do not heed the IBM documentation and on-line help on this topic, which 
tells you that if LS_MULTIPLESEL is selected, LSJEXTENDEDSEL should be 
too. If you specify both, only LS_EXTENDEDSEL will apply. 


LS_OWNERDRAW gives the owning dialog the power to display bitmaps, for 
example, as list items instead of just plain text (the default). 
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We won’t be creating any owner-drawn controls in this book, but if you 
remember that the data object associated with a list box item can be a 
bitmap, you’ll be able to draw a list box easily that displays bitmaps instead 
of strings. 


By default, a list box adjusts its height to be an even multiple of the height of 
the items it contains. That way, an item that appears in the list box always 
appears complete. If you set LS_NOADJUSTPOS, some portion of the bottom 
part of the last item or the top part of the top item might be invisible. (See 
Figure 14-2 for an example). 



Figure 14-2: Partial lines may occur when 
LS_N0ADJUSTP0S is specified. (Note "Item 5" in 
left-most list box.) 


Sending list box messages 

There are seventeen messages that you can send to a list box as shown in 
Table 14-2. (And if you think that’s a lot, you should see multiline edit fields!) 
Fortunately, most of the messages are pretty easy to use once you figure 
them out. 

To use LM.DELETEALL, LM_DELETEITEM, LMJNSERTITEM, and LMJNSERT- 
MULTIITEMS, keep in mind that when you pass a text string to the list box, it 
copies that string over. So you can and should dispose of your copy of the 
string independently of the list box. In other words, even though you’re pass¬ 
ing a pointer to the data, the list box copies the data into its own space, so 
that you may use the insertion and deletion messages without having to keep 
track of what you passed. 
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Table 14-2 List Box Messages 

Message 

Function 

LIVLDELETEALL 

Delete all items from the box. 

LM_DELETEITEM 

Delete the indexed item 1 . 

LMJNSERTITEM 

Insert the item (a PSZ in mp2) at index 1 . 

LMJNSERTMULTIITEMS 

Insert the array of strings indicated by mp2 
according to the LBOXINFO structure passed as 
mpl. 

LM_QUERYITEMCOUNT 

Return the number of items in the box. 

LM_QUERYITEMHANDLE 

Return a handle to indexed item's associated 
object 1 . 

LM_QUERYITEMTEXT 

Put the indexed item's text in the PSZ passed 
as mp2, but no more than the amount specified 
by SH0RT2 of mpl. Return the number of 
characters in the passed text as a SHORT. 1 

LM_QUERYITEMTEXTLENGTH 

Return the length of the string for the indexed 
item 1 . 

LM_QllERYSELECTION 

Return the first selected item positioned after 
the indexed item 1 . 

LM_QU ERYTO P1N D EX 

Return the index of the item currently visible at 
the top of the list box. 

LM_SEARCHSTRING 

Search for a string (mp2) starting from the 
indicated item (SH0RT2 in mpl) and according 
to the option specified (SH0RT1 in mpl). 

LM_SELECTITEM 

Set the indexed item to be selected or not 
based on the BOOL in mp2J 

LM_SET!TEMHANDLE 

Set the associated object of the item indexed 1 to 
the handle passed as mp2. 

LM_SETITEMHEIGHT 

Set the height of items displayed to be mpl. 

LM_SETITEMTEXT 

The indexed item should contain a copy of the 
text pointed to by mpZ. 1 

LM_SETITEMWIDTH 

Set the item width to mpl. Applies only to 
LS_H0RZSCR0LL style list boxes. 

LM_SETT0P INDEX 

Scroll to the indexed item 1 . 


'Except for LM_SEARCHSTRING,the indexed item is always indicated by the zero- 
based index stored as SH0RT1 in mpl. 
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By contrast, when you use LM_SETITEMHANDLE to associate an object with 
a text string, you are actually passing a handle for the list box to use. The list 
box cannot know how or when to dispose of the memory (if any) that this 
object consumes. 

Therefore, when disposing of a list box containing only text items, you need 
do nothing but destroy the window. When disposing of a list box that also 
contains data objects, you should use LM_QUERYITEMHANDLE for each item 
in the list box and dispose of any associated objects before disposing of the 
rest of the dialog. 

LM_QUERYITEMTEXTLEN and LM_QUERYITEMTEXT are two messages you 
use together. The first tells you how much space you need to hold the item’s 
text (not counting the null terminator) and the second copies the item’s text 
into a local buffer. 

LM_SETITEMHEIGHT and LM_SETITEMWIDTH allow you to control how 
much space each item has. If the list box doesn’t scroll horizontally, then the 
item width is the width of the scroll box and LM_SETITEMWIDTH has no 
effect. These messages are probably used most often when a list box displays 
something other than text. 

A few of these messages require a little more explanation, and the following 
sections include code excerpts that show how you would actually use the 
messages. 


List box indexes 

SHORT 1 of mpl is always the index of the item being referred to in any list 
box message (that refers to a specific item). Usually this is a number from 0 
to n-1, where n is the number of items in the list, but it can also be LIT_END, 
LIT_SORTASCENDING, or LIT.SORTDESCENDING. 

Here’s code that I used to put some items in the first list box shown in Figure 
14-1. (The other code shown here is given so that you’ll have a reference for 
adding this code to your program.) 

LBOXINFO Ibi; 
i n t i ; 

PSZ *item[5] = {"Item 1", "Item 2", "Item 3", "Item 4", "Item 5"}; 

h a b = W i n I n i t i a 1 i z e (0); 

hmq = WinCreateMsgQueue(hab, 0); 

if (!WinRegisterClass(hab, szClassName, ClientWndProc, 

CS_SIZEREDRAW, 0)) 
fail = TRUE; 
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hwndFrame = WinLoadDlg(HWND_DESKTOP, HWND_DESKTOP, 

ClientWndProc, 0, LISTBOXPROGRAMID, NULL); 


for (i =0; i <5 ; i =i +1 ) { 

WinSendDlgItemMsg(hwndFrame, LID_MULT, 
MPFROMSHORT(LIT_END), 


LM_INSERTITEM, 
MPFROMP(1tem[i])) ; 


Single-item insertion, as you can see, is no big deal. 


inserting multiple items 



OS/2 Warp added a new API for inserting multiple items into a list with a sin¬ 
gle call. It requires a pointer to an LBOXINFO structure (lbi is declared in the 
previous code sample), and an array of PSZs (the variable item from the pre¬ 
ceding code sample). 


You could replace the loop from the code sample with a single call just by 
doing this: 


memset(&1bi , 0, sizeof(1bi )); 
lbi.1Itemlndex = LIT_S0 RTASCENDING; 

1bi.ulItemCount = 5; 

WinSendDlgltemMsg(hwndFrame, LID_EXT, LM_INSERTMULTITEMS, 
MPFROMP(&1bi), MPFROMP(item)); 


Simple, isn’t it? 



Don’t let the memset fool you. LBOXINFO has only two meaningful fields, 
lltemlndex and ulltemCount. But as with many other OS/2 data structures, 
the structure itself is larger and must be padded with zeroes. (OS/2 reserves 
the right to use these fields for undisclosed purposes.) 


Finding out which items are selected 

The LM_QUERYITEMSELECT message has a number of options that help you 
find out which item, or which set of items in a multiple-select list box, is cur¬ 
rently selected. 

Here’s how to query which items are selected in a multiple-select list box 
(this is from the event handler of LISTBOX.C): 

int i = LIT_FIRST; 

MPARAM mp; 
char c[ 1 0 0 0 ]; 
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/*event handler*/ 
switch(msg) { 

case WM_COMMAND: 
switch(SHORTlFROMMP(mpl)) { 
case BID_QUERY: 
do { 

i = WinSendDlgItemMsg(hwnd, LID_MULT, 

LM_QUERYSELECTION, MPFROMSHORT(i), 0); 
if (i != LIT_NONE) { 

WinSendDlgItemMsg(hwnd, LID_MULT, 

LM_QUERYITEMTEXT, MPFR0M2SH0RT(i, 1000), 

MPFROMP(c)); 

WinSendDlgItemMsg(hwnd, LID_MULTEXT, 

LM_INSERTITEM, MPFROMSHORT(LIT_END), 

MPFROMP(c)); 

} 

} while (i != LIT_N0NE ); /* enddo */ 
return 0; 

} 

break; 

LM_QUERYSELECTION returns the first item after the item index passed as 
mpl. Since the first item could be selected, you use a special define 
(LIT_FIRST) to tell PM to include the first item as part of the search for selec¬ 
tions. You can also use LIT_CURSOR to tell PM to start the search from where 
the list box cursor (or highlight bar) is currently positioned. 

The list box returns LIT_NONE if no items after the current one are found. 
Otherwise, it returns the (zero-based, as always) index of the next selected 
item. To find all the items selected, you can repeatedly pass this index back 
to the list box with LM_QUERYSELECTION until LITJNONE is returned. 

The code example shown finds the selected items in the leftmost list box 
(LID_MULT) and inserts them into the rightmost list box (LID_MULTEXT). 


Searching for a string in the list 

If you need to search for a string in the list box items, you can use the 
LMJSEARCHSTRING message. LMJSEARCHSTRING is the only list box mes¬ 
sage that does not use SHORT1 of mpl to indicate the starting item, but uses 
SHORT2 of mpl. Otherwise, it can be set to LIT_FIRST, just as LM_QUERY- 
SELECTION can be. 
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SHORTl of mpl is one or more of the following options: 

1 v* LSS_CASESENSITIVE, so that “item” won’t match “ITEM,” “iTem,” and so 
;; forth 

^ LSS_PREF1X, so that “Item” matches “Item 1” but not “1 Item” 
v 0 LSS_SUBSTRING, so that “Item” matches both “Item 1” and “1 Item” 

(Obviously LSS__PREFIX and LSS_CASESENSITIVE shouldn’t both be specified.) 

The wacky thing here is that the list box doesn’t do case-insensitive 
searches, so if you don’t specify LSS_CASESENSITIVE the search will always 
fail. 

Here’s a sample of how to do a search that responds to the Search button 
shown in Figure 14-1: 

case PID_SEARCH: 

i = WinSendDlgItemMsg(hwnd, LID_EXT, 

LM_SEARCHSTRING, 

MPFROM2SHORT(LS S_CAS ESENSITIVE, LIT_FIRST), 

M P F ROM P("Item")); 

sprintf(c, "%d in LID_EXT contains 'item'.", i); 
if (i != LIT_N0NE) 

WinMessageBox(HWND_DESKTOP, hwnd, 
c, "FOUND!", 0, 0); 
return 0; 


List box callbacks 

The WC_LISTBOX notifies its owner when certain events are occurring or 
have occurred. Most of these notifications occur swith the WM_CONTROL 
method. As always, the two shorts in mpl are the control ID and the notifica¬ 
tion code. (Possible notification codes are listed in Table 14-3.) 

These callbacks are pretty self-explanatory. Note that pressing the Enter key 
generates an LN_ENTER message but also causes the default button to be 
pressed. 

List boxes also send WM_DRAWITEM and WM_MEASURE messages to their 
owners, but these are used primarily for LS_OWNERDRAW style list boxes. 
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Table 14-3 List Box WM_C0NTR0L Callbacks 

Callback 

Description 

LN_ENTER 

The Enter key has been pressed orthe mouse has been 
double-clicked. 

LN_KILLFOCUS 

The list box is about to lose the focus. 

LN_SCR0LL 

The list box is about to scroll horizontally. 

LN_SETFOCUS 

The list box is about to receive the focus. 

LN_SELECT 

The item is being selected or deselected. 


The Combination Box 

By contrast, the combination box is a simple window class. It offers only a 
few styles, responds to only a few messages, and has only one callback. 

Because the combo box is a control that combines the entry field and list box 
classes, many of the messages and callbacks it uses are similar to those of 
the entry field and the list box. 

The combo box may be one of three styles, as shown in Table 14-4. 


Table 14-4 Combo Box Styles 

Style 

Description 

CBS_SIMPLE 

The entry field and list box controls are visible at all 
times. 

CBS_DR0PD0WN 

The list box control is hidden until the user causes it to 
drop down. 

CBSJDROPDOWNLIST 

The user cannot type anything into the entry field, but 
instead must cause the list box to be dropped down, 
and must make a selection from that box. 


CBS_SIMPLE and CBS_DROPDOWN allow users to type in the entry field, 
which means you must validate the data as your application requires. These 
kinds of combo boxes are good for “history lists,” where you’re merely show¬ 
ing users what they have entered in the field before, and allowing them to 
select it rather than retype. 
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CBS_DROPDOWNLIST, on the other hand, is like a compact form of a single¬ 
selection list box. Users may select only from the choices given, and their 
choice is displayed in the entry field. 

Combo boxes respond to the same messages that entry fields and list boxes 
do, plus three new ones of their own, as shown in Table 14-5. 


Table 14-5 Combo Box Messages 


Message 

Description 

CBM_HIUTE 

Set the highlight state of the drop-down button based 
onmpl (TRUE or FALSE). 

CBMJSLISTSH OWING 

Is the list box visible? 

CBM_SHOWLIST 

Show or hide the list box based on mpl. 


The drop-down button is the button to the immediate right of the entry field. 
If this button is highlighted, like other buttons the indicator appears to be 
depressed. 

As always, these messages may be used to cause some change programmati¬ 
cally in the combo box, but the combo box itself will respond to user input as 
appropriate. 

The combo box has just one callback, WM_CONTROL. The second short of 
mp2 may be one of seven codes, all of which are analogous to events that 
might occur in either an entry field window or a list box window. Table 14-6 
shows the possible notify codes. 


Table 14=6 Combo Box Notification Codes 


Style 

Description 

CBN_EFCHANGE 

The entry field has changed. (Sent afterthe change has 
been shown.) 

CBN_MEMERROR 

The entry field was unable to allocate the requested 
memory. 

CBN_EFSCROLL 

The entry field is about to scroll. 

CBN_LBSELECT 

An item in the list box has been selected. 

CBN_LBSCROLL 

The list box is aboutto scroll horizontally. 

CBN_SHOWLIST 

The list box is aboutto be displayed. 

CBN_ENTER 

Enter was pressed, or the list box was double-clicked. 
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Conclusion 

The trick to using any kind of list box is to manage the items correctly. The 
WPS-biased user may consider the list box a kind of primitive control, com¬ 
pared to the container, and I tend to agree. At the same time, the list box, and 
especially the combo box, are much more economical with screen real estate 
than are containers. 





In This Chapter 

The definition guide to spin buttons 
That’s it, just spin buttons! 


^mo far I’ve nagged you about not letting the user type in invalid data, but I 
haven’t really shown you any alternatives to entry fields—except the list 
box, which is kind of a silly tool to use for numeric input. 

Spin buttons are good for numeric input, and can also be used as compact 
single-select list boxes, because they respond to the cursor up and cursor 
down keys, and because they have a spin arrow control that the user can 
click on to scroll through the choices. They can also be like a radio button 
group, in that exactly one item must be selected. 

Spin buttons can act together to give the appearance of a single window with 
several spin fields. For example, you could create a set of controls for enter¬ 
ing a date that contained three spin buttons (one for day, one for month, and 
one for year), but display only one set of spin arrows for all three. (We’ll do 
this in the upcoming sections.) 

The same functionality would require three list boxes or combo boxes if you 
used those controls. With radio buttons, you’d end up taking up a lot of valu¬ 
able screen real estate. 

Before continuing, follow our usual practice of copying over the CONTROL1 
framework (the .H, .C, and .RES files), and then build a dialog like the one 
shown in Figure 15-1. 

The three spin buttons shown in the figure are SP_DAY, SP_MONTH, and 
SP_YEAR. Use your resource editor to make SP_DAY and SP_MONTH servant 
spin buttons and SP_YEAR a master spin button. (The group box is decora¬ 
tive. You may leave it out.) The button is PB_DISPLAY. 
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Date Group- 
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Figure 15-1: 


The spin 
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button 


dialog. 



Spin Button Stifles 

Spin button controls can be created with several options, but they aren’t 
really related, so I’ll describe them here one at a time. 

SPBS_MASTER and SPBS_SERVANT indicate that the spin field is a master or 
a servant. If there is only one spin field, it should be an SPBS_MASTER. A ser¬ 
vant has no spin arrows of its own. It spins when it has the focus and the user 
presses the cursor key, or when the user clicks on the master’s spin arrows. 
(More on this later.) 

To specify what the user can enter in the entry field portion of the spin button 
control, use SPBS_ALLCHARACTERS (any character), SPBS_NUMERICONLY 
(zero through nine, and the minus sign only), and SPBS_READONLY (nothing). 
With SPBS_READONLY set, the user must scroll through the choices given by 
using the cursor keys or the spin arrow. (For Figure 15-1, the day and year 
spin buttons should obviously be set to SPBS_NUMERIC only.) 

You can justify the text in a spin button with SPBS_JUSTLEFT, SPBS_JUST- 
RIGHT, and SPBS_JUSTCENTER. 

You can specify that no border be drawn around a spin button by using 
SPBS.NOBORDER. 

Using SPBSJFASTSPIN you can specify that the spin button should spin faster 
the longer a spin arrow is held down. When you set this option, by the way, 
you are allowing the spin button to skip over entries, so if it is important that 
the spin button display every entry as it spins, don’t use this. You shouldn’t 
use this option for a master spin button that has servants either. 

Normally, a spin button presents numbers as 1, 10, and 100, but you can 
change that with SPBS_PADWITHZEROS. This option causes a maximum of 
eleven zeros to be shown to the left of the number. (The number actually 
shown depends on the width of the field, but it is never more than eleven.) 
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Spin Button messages 

The key to understanding spin button messages is realizing that a spin but¬ 
ton can offer choices from an array of text items as well as a range of LONG 
integer possibilities. This, unfortunately, complicates querying and setting 
the value of a spin button. (Fortunately the complications are more theoreti¬ 
cal than practical, and the spin button is quite easy to use, as you’ll see.) 

Table 15-1 lists some of the messages twice to illustrate the differences in 
calling when the spin button is a range of integers (LONG) versus when the 
spin button is an array of text choices (PSZ). 


Table 15-1 Spin Button Messages 

Message 

Applies To 

Description 

S PB M_0 VERR1D ES ETU M ITS 

LONG only 

Sets range to upper (mpl) and lower (mp2) limits. 
Does not change current spin button value, even 
if the value is outside the new bounds. 

SPBM_QUERYLIMITS 

LONG only 

Returns upper (mpl) and lower (mp2) limits. 

SPBM_QUERYVALUE 

LONG 

Sets mpl (a PLONG) to the control's current 
value. SH0RT1 of mp2 is 0. SH0RT2 of mp2 is an 
option from Table 15-2. 

SPBIVLQUERYVALUE 

PSZ 

Sets mpl (a PSZ) to the control's current value. 
SH0RT1 is the length of the PSZ. SH0RT2 of mp2 
is an option from Table 15-2. 

SPBIVLSETARRAY 

PSZ only 

Sets the control to use an array of text items (mpl). 
mp2 contains the number of items in the array. 

SPBM_SETCURRENTVALUE 

LONG 

Sets the control to the LONG value in mpl. 

SPBIVLSETCURRENTVALUE 

PSZ 

Sets the control to be the index (indicated by 

LONG in mpl) of the array. 

SPBM_SETLIMITS 

LONG only 

Sets the range of the spin button to mpl (upper 
bound) and mp2 (lower bound). Changes the spin 
button's current value if it is outside the new 
bounds. 

SPBM_SETMASTER 

Both 

Sets the spin button's masterto the handle in mpl. 

SPBM_SETTEXTLIMIT 

Both 

SH0RT1 of mpl contains the new maximum 
number of characters allowed (255 or fewer). 

SPBIVLSPINDOWN 

Both 

SH0RT1 of mpl contains the number of entries to 
spin back, which the control does upon receiving 
this message. 

SPBIVLSPINUP 

Both 

SH0RT1 of mpl contains the number of entries to 
spin forward, which the control does upon 
receiving this message. 
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The SPBM_QUERYVALUE call, besides returning the current value, can also 
affect the value in the spin button. SHORT2 of mp2 can be set to one of the 
values shown in Table 15-2 to create an additional effect. 


Table 15-2 SPBM_ 

QUERYVALUE Options 

Option 

Description 

SPBQJJPDATEIFVALID 

For a text spin button, change the value to match an 
entry in the spin array exactly if only the case does 
not match. If it's not a valid entry, restore to the last 
valid entry. 

SPBQ_ALWAYSUPDATE For a numeric spin button, change an out-of-range 

numberto the high or low bound. For a text spin 
button, change an invalid entry to the last valid value. 

SPBQJDONOTUPDATE 

Don't change the value. 


Because the Dialog Editor does not allow you to set the values for a spin but¬ 
ton, you’ll need to use the set limits messages to set up the spin buttons’ 
ranges. I like to do this immediately after loading the dialog: 


hwndDlg = WinLoadDlg(HWND_DESKTOP, HWND_DESKTOP, 

ClientWndProc, 0, SPINPROGRAMID, NULL); 

WinSendDlgItemMsg(hwndDlg, SP_DAY, SPBM_0VERRIDESETLIMITS, 

MPFR0ML0NG(31), MPFR0ML0NG(1)); 

WinSendDlgItemMsg(hwndDlg, SP_YEAR, SPBM_SETLIMITS, 

MPFROMLONG( 1995), MPFROMLONG( 1974)) ; 


I used SPBM_0VERRIDESETLIMITS for arbitrarily SP_DAY and SPBM_SET- 
LIMITS for SP_YEAR. If you run this code, however, it makes the distinction 
between the two evident. SP_DAY will still contain a blank value, while 
SP_YEAR will contain 1974. SPBM_SETLIMITS will cause the spin button to 
adjust an out-of-range value to the nearest in-range value. 

For any text list, however, you’ll need to use SPBM_SETARRAY: 

PSZ months[] = {"January", "February", "March", 

"April", "May", "June", "July", "August", 

"September", "October", "November", "December"}; 
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WinSendDlgItemMsg(hwndDlg, SP_M0NTH, SPBM_SETARRAY, 

MPFROMLONG(months), MPFROMLONG(12)); 

mpl in an SPBM_SETARRAY message is an array of strings, and mp2 is the 
number of elements in the array. 

The other thing the Dialog Editor doesn’t allow is establishing a connection 
between servants and masters, so that also must be done by sending the con¬ 
trols a message: 

HWND spin; 

spin = WinWindowFromID(hwndDlg, SP_YEAR); 

WinSendDlgItemMsg(hwndDlg, SP_DAY, SPBM_SETMASTER, 

MPFROMP(spin ), 0); 

WinSendDlgItemMsg(hwndDlg, SP_M0NTH, SPBM_SETMASTER, 

MPFROMP(spin ), 0); 

This is an important piece of code to try out because otherwise the 
servant/master relationship is not at all obvious. All that the servant/master 
relationship means is that the servant controls don’t have their own spin 
arrows and that they will use the master’s spin arrows instead. 

The user spins the servant with the master’s arrows by first focusing the 
servant spin button using the mouse or the Tab key, and then by clicking on 
the spin arrows. If none of the spin buttons are focused when the user clicks 
on the spin arrows, the master spin button will scroll. 

Finally, the other spin button message you’re likely to use is SPBM_QUERY- 
VALUE. There are two ways to query a spin button’s value, as shown in the 
following code: 

long day, year, selmo; 
char month[10]; 
char message[1000]; 

case WM_COMMAND: 

switch(SH0RT1FROMMP(mpl)) { 
case P B_DISP LAY: 

WinSendDlgItemMsg(hwnd, SP_DAY, SPBM_QUERYVALUE, 

MPFROMP(&day), MPFR0M2SH0RT(0, SPBQ_ALWAYSUPDATE)); 

WinSendDlgItemMsg(hwnd, SP_M0NTH, SPBM_QUERYVALUE, 

MPFROMP(month), MPFR0M2SH0RT(10, SPBQ_UPDATEIF- 
VALID)); 

WinSendDlgItemMsg(hwnd, SP_YEAR, SPBM_QUERYVALUE, 

MPFROMP(&year), MPFR0M2SH0RT(0, 0)); 
sprintf(message, "%d %s %d", day, month, year); 
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WinMessageBox(HWND_DESKTOP, HWND_DESKTOP, message, 
"Date Selected", 0, MB_0K | MB_INFORMAT 10N); 
return 0; 

} 


The first way is to send SPBM_QUERYVALUE along with the address to a 
LONG and a buffer length of zero (in SHORT 1 of mp2). The spin button inter¬ 
prets this to mean that you want the value of the spin button returned as an 
integer value. 

So, if the user has selected 31 in SP_DAY, the day variable will be set to 31. If 
the user has selected 1975 in SP_YEAR, the year variable will be set to 1975. 

Now, if the user sets SP_YEAR to 0 or 123456789, the year variable will be set 
to those values, even though they are out of range. 

But if you use SPBQ_ALWAYSUPDATE when querying a spin button, you 
force the spin button to a valid value, and that value is what is returned. So 
for SP_DAY, if the user enters -10, the day variable will be set to 1. If the user 
enters 100, the day variable will be set to 31. 

You can use this same approach with a text spin button to get the position of 
the current selection in the array, and we’ll do this in the callback section 
coming up. 

In some cases, however, a spin button may present only a certain number of 
valid options, not all the valid options, and the user may enter something dif¬ 
ferent in the entry field. To retrieve the value the user has typed, you pass 
SPBM_QUERYVALUE an address to a string buffer as mpl, and the length of 
the buffer in SHORT2 of mp2. (The length passed should be the total length 
of the buffer—the spin button window will use the entire length including one 
space for the null terminator.) 

If SPBQJJPDATEIFVALID is used, which means that if the user types an entry 
that’s correct in everything except case, the spin button corrects it based on 
what you passed it in the array you used with SPBM_SETARRAY. 

So in the case shown, if the user enters JANUARY or JaNuary or (one of my 
favorites) jANUARY, SP_MONTH will change that to January. 


Spin button callbacks 

Spin buttons have only one kind of callback message, and that is WM_CON- 
TROL. As always, the first short of mpl contains the ID of the spin button and 
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the second contains one of the notification codes shown in Table 15-3. mp2, 
as usual, contains the handle of the spin button. 


Table 15-3 Spin Button Callbacks 

Callback 

Description 

SPBNJJPARROW 

Up arrow was clicked or up cursor key was pressed. 

SPBN_D0WN ARROW 

Down arrow was clicked or down cursor key was 
pressed. 

SPBN_SETFOCUS 

About to receive focus. 

SPBN_KILLFOCUS 

About to lose focus. 

SPBN_ENDSPIN 

The user stopped spinning the button. 

SPBN_CHANGE 

The contents changed. 


We can use these notifications to correct a deficit in the date dialog as it cur¬ 
rently stands: If the user switches the month to February, SP_DAY really 
shouldn’t be allowed to scroll to 31 anymore. 

We have an interesting situation here that we haven’t had to deal with before. 
We have three spin buttons in the dialog, any of which could use these call¬ 
backs, so we’ll finally have to use SH0RT2 of mpl to determine if it is the 
month sending us the SPBN_CHANGE message: 

long dim[12] = (31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31}; 

case WM_C0NTR0L: 

switch(SHORT1FROMMP(mpl)) { 
case SP_M0NTH: 
switch(SH0RT2FR0MMP(mpl)) { 
case SPBN_CHANGE: 

if (WinSendDlgltemMsgChwnd, SP_M0NTH, SPBM_QUERYVALUE, 
MPFR0ML0NG(&selmo), MPFR0M2SH0RT(0, SPBQ_UPDATEIFVALID))) 

Wi nSendDl gItemMsg( hwnd , SP__DAY, S PBM_S ETLIMITS , 
MPFROMLONGCdim[selmo]), MPFROMLONG(1)); 
return 0; 

} 

break; 

} 

break; 


First we set up an array containing the number of days in each month (it 
seemed a bit absurd to worry about leap years for this example, so we won’t 
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include them). Then we detected the WM_CONTROL message sent by 
SP_MONTH with the notification code of SPBN_CHANGE. 

In order to set the new SPJDAY limits, we have to find out which month was 
selected. And since our data is contained in a numeric array, we don’t want 
to get back January, February, and so on. Instead we want the month’s posi¬ 
tion in the array: 0 for January, 1 for February, and so on through 11 for 
December. 


In addition, because the SP_MONTH control might contain anything , not just 
a valid month, we did something we haven’t done much of up to this point: 
We actually checked the return from WinSendDlgltemMsg. If it is false, the 
value in the spin button does not match any of the entries in the array and 
SPBM_QUERYVALUE cannot, therefore, return an entry number for it. 


Otherwise, we use the value returned in selmo to set the new limits for the 
SP_DAY spin button. We used SPBM_SETLIMITS here, which will bring the 
SP_DAY value into range. (So if the user has selected 31 January and clicks 
the month over to February, the day is reset to 28.) 



We also used SPBQJJPDATEIFVALID here and not SPBQ_ALWAYSUPDATE. If 
we had used SPBQ_ALWAYSUPDATE, we wouldn’t bother to check the return 
from the SPBM_QUERYVALUE because it would always be valid. 

At the same time, since we’re checking every time we get an SPBN_CHANGE 
message, using SPBQ_ALWAYSUPDATE would create an exercise in frustra¬ 
tion for the user, who would be trying to type something in while we con¬ 
stantly changed it. If it’s absolutely necessary that the value always be valid, 
switch the spin button to read only, and the user will be forced to scroll 
through the valid options. 


Conclusion 

Your arsenal of controls has been increased again, and fairly powerfully. The 
spin button can replace a single-select list box and an entry field that accepts 
only numbers. 


Use it wisely! 



Chapter 16 

Sliders 


in This Chapter 
The basics of sliders 
Slider messages and Callbacks 


JM slider is the computer’s way of representing analog data. The slider arm, 
f 1 as it is called, moves along a track either horizontally or vertically, and 
lets you represent approximations, since the user doesn’t type in any specific 
value. 


Of course, the slider refers to a specific value at each point along the way, 
and it’s up to you to decide exactly how fine a point you’re going to put on 
the issue, so to speak. You can use the tick mark nearest the current slider 
position, or you can count the pixels from the end that the arm is closer to. 

And that’s the problem with this control. Virtually everything is up to you. 
The dialog editor helps you with some aspects of adding a slider, but not 
very many. And that means you must design your sliders programmatically. 

Figure 16-1 shows the dialog design we’ll be using for this chapter. The three 
controls are SL_SLIDER, PB_QUERY, and SP_SPIN. That thing in the lower 
right-hand corner that looks like an entry field is in fact a spin button, which 
is set up as a servant and as read only. 
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When you first add the slider to create the dialog in Figure 16-1, the Dialog 
Editor asks you to enter a number for scalel and scale2. Enter 36 for scalel 

The slider dialog you build with the Dialog Editor will not look exactly like 
Figure 16-1. We’ll have to write commands in our code to set up the slider 
this way, due to the Dialog Editor’s limitations. 


We’re going to use the Query button to figure out which increment the slider 
arm is closest to, but we’re going to have the spin button track every move¬ 
ment of the slider arm and display its current position in pixels. 


As in other chapters, I’ll show examples of how to do stuff with sliders by giv¬ 
ing code snippets. Unlike other chapters, however, the entire listing is 
included at the end because there’s enough code scattered throughout the 
chapter to make it difficult to follow by adding a snippet here and there. 


Slider Basics 


A slider consists of a track, an arm, and usually some tick marks and associ¬ 
ated text that describe the slider’s position to the user. 



There are a number of words that you should know to use sliders happily: 

I is* Arm : The thing that moves along the track. It usually resembles a rectan¬ 
gular knob, or one of those transporter controls from the old Star Trek 
series. 

v* Detent : A specific position on the track that has a specific value (that 
you assign). This need not bear any relation to any other aspect of the 
slider. This word comes from mechanical engineering and refers to a 
part used to stop or control motion in a machine. It should not be con¬ 
fused with detente , meaning a lessening of tension or hostilities between 
two parties (like Microsoft and IBM). 

is* Home : The “zero” position of a slider. Thhis is usually the bottom of a 
vertically oriented slider or the left end of a horizontally oriented one. 

us Scale : The number of increments, or ticks, a slider is divided into. A 
scale of 100 means that the slider is divided into 100 ticks. If the scale is 
200 pixels long, that scale consists of 100 ticks of 2 pixels each. A 
WC_SLIDER window can have two scales, but only one is used. (More on 
this oddity later.) 

! ^ Tick : An increment of the slider. (See Scale .) Ticks may have text associ- 
1 ated with them. 
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i v* Tick mark : A straight line that extends outward from the track and per¬ 
pendicular to it. Often on a track there will be more than one size of tick 
marks, as on a ruler, where inches are designated as the largest tick 
marks, half-inches are smaller, quarter-inches are smaller still, and 
eighth-inches are the smallest tick marks. 

Logically, then, if you were trying to emulate a yardstick, you might give the 
slider a scale of 36 ticks (one for each inch), and create a tick mark for each, 
with large tick marks for the foot. 

There’s an important relationship between the ticks and the actual number of 
pixels on the screen, and this is where detents come in. In our ruler example, 
say that the slider was 36 times 3 pixels long, or 108 pixels. That gives three 
pixels for each tick. If you want pixel 50 to have some special meaning, you 
set a detent there. 

Sliders have a wide variety of styles and, like other controls, certain options 
are exclusive of each other. To help clarify this, the options are presented 
here in text rather than table format. 

A slider may be positioned horizontally (SLS_HORIZONTAL) or vertically 
(SLS_VERTIC AL). 

The slider itself does not necessarily take up the entire window. There is a 
margin of window space around it, which may be filled with tick marks or 
other text, or left blank. You can position the slider within the window by set¬ 
ting SLS_CENTER, SLS.BOTTOM, or SLS_TOP (horizontal sliders), or 
SLS_CENTER, SLS_RIGHT, or SLS_LEFT (vertical sliders). By positioning the 
slider to one side or the other, you leave more room for descriptive text in 
the window. 


A slider’s scale may appear in one of two positions. This is often misleadingly 
described as though the slider actually had two scales. It does not. A slider 
has one scale that appears either to the right or above the slider (scalel), or 
to the left or below the slider (scale2). You choose SLSjPRIMARYSCALEl or 
SLS_PRIMARYSCALE2 depending on where you want the tick marks to 
appear. 



This issue is confused even more by the fact that the WCJ5LIDER definition 
refers to a primary scale and allows (even insists ) that you set a value for both 
scales. 

For example, if you add a slider to a dialog using the Dialog Editor, 
WC_SLIDER asks you to put in a value for Scale 1 and for Scale 2. You can use 
only one of those. If you were thinking you could build a thermometer-type 
scale with Fahrenheit on one side and Centigrade on the other, you can for¬ 
get it — the scale won’t do that. 
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You may find that you want to change your scale during the development of a 
program and that you are given no way to do this. If that happens, you can 
open the .DLG file for the resource and edit it directly. 

This is the .DLG file for Figure 16-1: 


#ifndef 0S2_INCLUDED 
#include <os2.h> 

#endif 

DLGINCLUDE 1 "C:\WRITINGS\WARP\SOURCE\slider 


DLGTEMPLATE 100 LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 

DIALOG "Dialog Title", 100, 12, 6, 148, 84, WS_VISIBLE, 
FCF_SYSMENU | 

FCF_TITLEBAR 

BEGIN 

SLIDER 101, 0, 30, 145, 45, WS_GR0UP 

CTLDATA 12, 0, 36, 0, 0, 0 
PUSHBUTTON "-Query", 102, 0, 0, 40, 14 

SPINBUTTON 103, 88, 0, 48, 12, SPBS_READONLY | 

WS_GR0UP 
END 
END 


The boldface, underlined text to the right of the text that begins with CTL¬ 
DATA 12, shows where SCALE 1 (currently 36) and SCALE2 (currently 0) 
appear in a SLIDER resource definition. Normally one of these will be zero. 

You can change either number and recompile the resource to create a 
change in the slider. 

You can specify where home is for your horizontal slider with SLS_HOME- 
LEFT and SLS_HOMERIGHT. You can specify where home is for your vertical 
slider with SLS_HOMEBOTTOM and SLSJDOMETOP. 


Instead of dragging the slider arm directly, you can allow users to increment 
or decrement the slider arm by clicking on a set of buttons that appear along¬ 
side the slider. For a horizontal slider, specify SLS_BUTTONSLEFT or 
SLSJBUTTONSRIGHT. For a vertical slider, specify SLS_BUTTONSBOTTOM or 
SLS_BUTTONSTOP. If you don’t specify either option, your slider will have no 
buttons. 


By default, the slider is truly analog in that wherever the arm is dragged it 
stays, regardless of whether it is between tick marks. SLSJSNAPTOINCRE- 
MENT forces the arm to move to the nearest increment. 
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In other words, on a 200-pixel scale divided into 100 increments, the user can 
normally move the arm to any pixel on the scale, including, for example, the 
49th pixel (in between increments 24 and 25). With SLSJ5NAPTOINCREMENT, 
the arm will be moved automatically to either the 48th pixel (increment 24) 
or to the 50th pixel (increment 25, but it never allows itself to be dropped in 
between. 

You can use the slider as a progress gauge as well as an input device. To do 
this, specify SLS_READONLY and the user will not be able to move the slider 
arm. 

The SLS_RIBBONSTRIP option causes the track to be colored differently on 
one side of the arm than on the other. By default, the track between home 
and the arm is darker than the track between the arm and the end of the 
slider. This can create a mercury thermometer-type effect. 

If you really want to get into sliders, you can draw them yourself by specify¬ 
ing SLS_OWNERDRAW. We’re not masochistic enough to do that here. 


Slider Messages 



Sliders respond to only ten unique messages, most of which are straightfor¬ 
ward. 

All the messages apply to the primary scale, of course. 

Any invalid parameter passed with a slider message returns the value of 
SLDERR_INVALID_PARAMETERS. 


For SLM_SETSLIDERINFO, the first USHORT of mpl tells the slider what info 
you are setting, and determines what should be passed in mp2. 

Table 16-1 shows the slider messages, and Table 16-2 shows the options you 
can use to set and query sliders. 
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Table 16-1 Slider Messages 

Message 

Description 

SLM_ADDDETEI\IT 

Places a detent mpl (USHORT) pixels from home. 

Returns the ID forthe detent (or zero for an error). 

SLM_QUERYDETENTPOS 

Returns the position of the detent whose ID matches 
the ULONG in mpl in SH0RT1 of MRESULT. 

SLM_QUERYSCALETEXT 

Puts the text associated with the tick mark indicated 
by SH0RT1 of mpl into the PSZ passed in mp2. The 
buffer length is indicated by SH0RT2 of mpl and 
should include space for the null terminator. Returns 
the number of characters actually copied. 

SLM_QUERYSLIDERINFO 

Returns slider information based on codes passed as 
SH0RT1 and SH0RT2 of mpl. (Seethe explanation 
following this table.) 

SLM_QUERYTICKPOS 

Returns (as two USHORTS) the xy position of a tick 
(numbered by a USHORT in mpl). 

SLM_QUERYTICKSIZE 

Returns the size of the tick mark (USHORT in mpl) as 
USHORT. 

SLM_REMOVEDETENT 

Removes the detent (ID is ULONG in mpl). 

SLIVLSETSCALETEXT 

Places text (PSZ in mp2) over the tick (USHORT in mpl). 

SLM_S ETSLI DERI N FO 

Changes some aspect of the slider based on options 
in SH0RT1 and SH0RT2 of mpl to the value specified 
in mp2 (ULONG). 

SLM_SETTICKSIZE 

Sets the tick (USH0RT1 in mpl) to the specified size 
(USH0RT2 in mp2). 


Table 16-2 Valid Options for Setting and Querying Sliders 

Request 

Description 

SMA_SHAFTDIMENSIONS 

SH0RT1 is the length of the shaft; SH0RT2 is 
the breadth of the shaft. 

SMA_SHAFTPOSITION 

SH0RT1 is the x-coordinate of the shaft; 

SH0RT2 is the y-coordinate of the shaft. 

SMA_SLIDERARMDIMENSIONS 

SH0RT1 is the length of the arm; SH0RT2 is 
the breadth of the arm. 

SMA_SLIDERARMPOSITION 

SH0RT1 is the distance from home; SH0RT2 is 
the total range. 
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For the SMAJ5LIDERARMPOSITION, the second USHORT of mpl may also be 
SMAJRANGEVALUE or SMAJNCREMENTVALUE. If SMA_RANGEVALUE is cho¬ 
sen, the values returned are in pixels. If SMAJNCREMENTVALUE is chosen, 
SHORT1 is returned in increments, and SHORT2 is not used. 

Table 16-1 can also be read as a table for querying slider information. The left 
column displays what is passed in SHORT 1 of mpl. (SMAJNCREMENTVALUE 
and SMAJRANGEVALUE are valid options for SH0RT2 of mpl when using 
SMA_SLIDERARMPOSITION.) The right column displays what is returned by 
the slider. 

You’re likely to use all of these messages every time you use a slider. 

The slider class allows you to set all the tick sizes at once by using 
SLM_SETTICKSIZE in conjunction with SMAJSETALLTICKS: 

WinSendMsg(slider, SLM_SETTICKSIZE, 

MPFR0M2SH0RT(SMA_SETALLTICKS, 10), 0); 

A specific tick number is anything from zero to the total number of ticks 
minus one. You will sometimes want to assign different values to different 
ticks. In the case of a ruler, for example, foot marks should be larger than 
half-foot marks, which should be larger than quarter-foot marks, which 
should be larger than inches. 

for (i=0;i<37;i=i+l) { 

j = 2; 

if ((( i+1)%3) — 0) j = 5; 
if ( (( i+1)%6) —0) j = 1 0; 
if (((i+1)%12)==0) j=20; 

WinSendMsg(slider, SLM_SETTICKSIZE, 

MPFR0M2SH0RT(i, j) , 0) ; 


You can assign text to any tick mark. WC_SLIDER centers that text over the 
tick mark: 


if (!WinSendMsg(siider, SLM_SETSCALETEXT, 
MPFROMSHORT(11) , MPFROMP("1"))) ; 



One common mistake is to not make the slider large enough to accommodate 
the scale text. The slider positions the text farther away from the track than 
the longest tick mark, which may well be outside the slider window, and 
nothing seems to happen when you set the text. 
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Querying the slider arm is as simple as passing the right message and parsing 
the result, as shown in this snippet activated by the Query button: 

mr = WinSendDlgItemMsg(hwnd, SL_SLIDER, SLM_QUERYSLIDERINFO, 
MPFR0M2SHORT(SMA_SLIDERARMPOSITION, SMA_INCREMENTVALUE), 

0 ) ; 

sap = SHORTlFROMMR(mr); 


Slider callbacks 

Sliders send their owners WM_CONTROL messages, with the second 
USHORT of mpl containing one of four notification codes: 


SLN_CHANGE 

SLN_KILLFOCUS 

SLN_SETFOCUS 

SLN_SLIDERTRACK 


Arm has moved 
About to lose focus 
About to get focus 

Arm is being dragged but has not been released 


The slider window also sends its owner the WM_CONTROLPOINTER message 
so that the owner knows when to change the pointer (which you won’t usu¬ 
ally do), and a WM_DRAWITEM message in case the owner wants to draw the 
slider itself (which you also won’t usually do). 





The slider, value set, notebook, and container controls are part of IBM’s CUA 
’91 interface specification. CUA stands for Common User Access, and was cre¬ 
ated to provide a, well, common way for the user to access programs. 

All of the controls we’ve looked at in previous chapters were part of the 
older, CUA ’89 specification. The four controls in the preceding list are part of 
CUA ’91, and all have the WM_CONTROLPOINTER and WM_DRAWITEM mes¬ 
sages in common. (This is presumably because IBM was enlightened 
between 1989 and 1991 as to the value of allowing the owner to draw the con¬ 
trol, and of changing the pointer when it passed over specific controls.) 


Of these notifications, you will be concerned mostly with SLN_CHANGE and 
SLN_SLIDFRTRACK. With the others, mp2 contains the handle of the slider, 
as we’ve come to expect. But with SLN_CHANGE and SLN_SLIDERTRACK, 
mp2 contains the new position of the slider arm (in pixels from home, not 
increments). 

That makes it possible for you to track the slider value as it changes without 
having to query it. Check out the code after WM_CONTROL in the following 
program listing: 
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//define INCL_GPI 
//define INCL_WIN 
//include <os2.h> 

//include "slider.h" 


/* ClientWndProc is a dialog procedure */ 

MRESULT EXPENTRY ClientWndProc(HWND, ULONG, MPARAM, MPARAM); 


int main 

/ 

(void) 




i 

HAB 

hab; 

/* 

anchor block handle 

*/ 

HMQ 

hmq; 

/* 

message queue handle 

*/ 

HWND 

hwndDlg; 

/* 

handles to windows 

*/ 

QMSG 

qmsg; 

/* 

message 

*/ 

char 

szClassName[] = 

"Sliding Into Home"; 


BOOL 

fail = FALSE; 





HWND slider; 

int i , j ; 

MRESULT mr; 

hab = WinInitia1ize(0); 

hmq = WinCreateMsgQueue(hab, 0); 

if (iWinRegisterClass(hab, szClassName, ClientWndProc, 
CS_SIZEREDRAW, 0)) 
fail = TRUE; 

hwndDlg = WinLoadDlg(HWND_DESKTOP, HWND_DESKTOP, 

ClientWndProc, 0, SLIDERPROGRAMID, NULL); 

slider = WinWindowFromID(hwndDlg, SL_SLIDER); 

/* 

WinSendMsg(siider, SLM_SETTICKSIZE, 

MPFR0M2SH0RT(SMA_SETALLTICKS, 10), 0); 

*/ 

for (i=0;i<37;i=i+l) { 


j = 2; 

if ( (( i+1 )%3)—0) j=5; 
if (( (i+l)%6)— 0) j = 10; 
if (((i+1)%12)—0) j = 20; 


WinSendMsg(siider, SLM_SETTICKSIZE, 
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MPFR0M2SH0RT(i, j ) , 0) ; 

} 

if (!WinSendMsg(slider, SLM_SETSCALETEXT, 

MPFROMSHORT(11), MPFROMP("1"))); 

if (!WinSendMsg(slider, SLM_SETSCALETEXT, 

MPFROMSHORT(23), MPFROMP("2"))) ; 

if (!WinSendMsg(slider, SLM_SETSCALETEXT, 

MPFROMSHORT(35), MPFROMP("3"))) ; 

mr = WinSendMsg(siider, SLM_QUERYSLIDERINFO, 

MPFROMSHORT(SMA_SHAFTDIMENSIONS), 

0); 

i = SHORTlFROMMR(mr); 

WinSendDlgltemMsg(hwndDlg, SP_SPIN, SPBM_SETLIMITS, 
MPFROMLONG(i ), MPFROMLONG(0 )); 

if ((fail ) | | (hab==NULLHANDLE) | | 

(hmq==NULLHANDLE) || (hwndDlg==NULLHANDLE)) 
WinMessageBox(HWND_DESKTOP, HWND_DESKTOP, 

"Unable to initialize application.", "ERROR!", 
0, MB_CANCEL | MB_ERR0R); 

el se 

while (WinGetMsg(hab, &qmsg, 0, 0, 0)) 

WinDispatchMsg(hab, &qmsg); 


WinDestroyWindow(hwndDlg); 
WinDestroyMsgQueue(hmq); 

WinTerminate(hab); 

return 0; 

} 


MRESULT EXPENTRY ClientWndProc(HWND hwnd, ULONG msg, MPARAM mpl, 
MPARAM mp2) 

{ 

MRESULT mr; 

SHORT sap; 

char message[1000]; 

/*event handler*/ 
switch(msg) { 
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case WM_CONTROL: 
swi tch(SH0RT2FR0MMP(mpl)) { 
case SLN_CHANGE: 
case SLN_SLIDERTRACK: 

WinSendDlgItemMsg(hwnd, SP_SPIN, 

SPBM_SETCURRENTVALUE,mp2,0); 
return 0; 

} 


case WM_COMMAND: 
swi tch(SHORTlFROMMPCmpl)) { 
case PB_QUERY: 

mr = WinSendDlgItemMsg(hwnd, SL_SLIDER, SLM_QUERYSLIDER- 
INFO, 

MPFR0M2SH0RT(SMA_SLIDERARMPOSITION, SMA_INCREMENTVALUE), 
0 ); 

sap = SHORTlFROMMR(mr); 

sprintf(message,"SIider arm at increment %d",sap); 

WinMessageBoxCHWND_DESKTOP, HWND_DESKTOP, 
message, "Query Slider Arm", 

0, MB_0K | MB_INFORMATION); 

return 0; 

} 

break; 

case WM_CLOSE: 

WinPostMsgChwnd, WM_QUIT, 0,0); 
return 0; 

} 


return WinDefDlgProc(hwnd, msg, mpl, mp2); 

} 



SLIDER.H is created by the dialog editor, as is SLIDER.DLG. To compile 
SLIDER.C you need to have only a SLIDER.RC file (like the one we made for 
CONTROL1) that looks like this: 

#inelude <os2.h> 

#include "slider.h" 


RCINCLUDE slider.dig 

Not much to it, is there? i 
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Conclusion 

We’re nearing the end of the part of this book devoted to controls, and you 
may already be detecting a slight change in the way things work. 

Sliders seem somehow different from other controls in the way they are 
accessed and used. Indeed, as you progress to the next chapter, and then 
later to the WPS part of the book, you’ll witness the change in OS/2 from tra¬ 
ditional function-oriented programming to something a little less nerdv. 








Chapter 17 

Value Sets 


In This Chapter 

The value of sets 

Different styles in value set cells 

Value set messages and callbacks 


AM value set is a grid containing a number of items (or cells , as I call them), 
¥ \ where the cells are uniformly sized and spaced in columns and rows 
within the value set window. Each cell displays a color, a graphic, or some 
text. 


A value set has a cursor, which takes the form of a box drawn around the cur¬ 
rently selected item. The user can move the cursor with the cursor keys or 
by clicking the mouse on another cell. 

I confess a certain inexplicable fondness for the value set control. Perhaps 
because, as a youth, I learned to program by rewriting computer games— 
most of which took place on playing fields made of columns and rows. (The 
value set would have been perfect for these.) 

In fact, Figure 17-1 shows a partial prototype for the classic computer game 
of Star Trek. In this game, the value set along the top represented quadrants 
in the area of space you were patrolling and what was in them. 

The value set underneath represented the quadrant you were currently in, 
showing the exact location of those objects and your own ship. 

We’ll use this dialog along with the usual framework to explore the value set 
window class. The Dialog Editor will not allow you to specify contents for the 
value sets, so just set up two 8x8 value sets. (The top one is called LRS for 
Long-Range Sensors; the bottom one is called SRS for Short-Range Sensors.) 
As usual there is a Query button (PB_QUERY). Above that are two spin but¬ 
tons called SP ROW and SP COL. 
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Like the slider example, the full listing for the value set appears at the end of 
this chapter, along with the usual code snippets. 


Value Set Styles 

Value sets are defined by one of five basic styles, which govern what they dis¬ 
play in their cells: VS_BITMAP, VSJCON, VS_TEXT, VS_RGB, or VS_COLOR- 
INDEX. 

An RGB value is a 4-byte integer indicating the intensity of red, green, and 
blue used to make up a color. The formula is (Red * 65536) + (Green * 256) + 
Blue. This allows you to specify any of a zillion colors that a monitor may be 
capable of displaying. 

The color wheel used in setting the system colors (shown in Figure 17-2) will 
help you get a feel for how this color system works. 

You have to click the Values button to make the Red, Green, and Blue spin 
buttons appear, m 

























Figure 17-2: 
OS/2's color 
wheel. 
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A color index refers to the specific logical table of colors in use at the time the 
program is running. With this scheme, the index refers to a specific entry and 
has no bearing on the physical makeup of that color. In other words, 0 could 
be black, 1 could be white, 2 could be red, and so on. 

Other than acknowledging the existence of the logical color table, we won’t 
be examining it in this book, m 

Although a value set has a specific type to which all items are set by default, 
each cell’s setting may be overridden individually to display any of the five 
possible types. So you could have a value set displaying text in all of its cells, 
and then decide to make one of the cells display a bitmap or color. The SRS 
in Figure 17-1 contains one item of each type. 

In addition to the basic style of the value set, VS_BORDER may be specified 
to indicate that the entire value set should have a border around it. VS JTEM- 
BORDER may be specified to indicate that each cell should have its own bor¬ 
der. Both the value sets shown in Figure 17-1 have VS_BORDER set, but only 
the LRS has VSJTEMBORDER set. 
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By default, a value set considers “home” to be the top left cell Column 1 is 
the leftmost column. You can make the rightmost column be column 1 by 
specifying the VS_RIGHTTOLEFT option. 

Lastly, you can control the drawing of the background of the value set by 
specifying VS_OWNERDRAW. Oh, rapture! (Actually, this feature might be 
useful in an application like this, because you could draw the background of 
the SRS with bitmaps of stars.) 


Value Set Messages 

The value set has only eight unique messages, as shown in Table 17-1. 

In a value set message, a cell is always specified by mpl, with the first 
USHORT being the row and the second USHORT being the column. Distances 
and sizes are always returned in numbers of pixels. 

The value set is somewhat anomalous in the world of OS/2 controls because 
the leftmost column and the topmost row are numbered 1, not 0. So row 1 
and column 1 indicate the upper left item of the value set. 

Also, the value set introduces an annoying little data type called VSTEXT. 
VSTEXT consists of two fields: the first is a PSZ called pszText that contains 
the text for a text item; the second is a ULONG called ulBufLen that contains 
the size of the PSZ buffer. 

For querying or setting the item attributes, you’ll use one of the five item 
types (V1A_BITMAP, VIA_COLORINDEX, VIAJCON, VIA_RGB, V1A_TEXT) 
along with, optionally, VLAJDISABLED, VIA_DRAGGABLE, VIA_DROPONABLE, 
or VIA_OWNERDRAW. 

A disabled item should appear “disabled” to the user. For text, that usually 
means the item is drawn in half-tone, and this is done automatically by the 
value set window. For other types of items, you’ll provide a suitable color or 
graphic that communicates the item’s disabled state. (You don’t have to do 
this, by the way. IBM just thinks you should , if possible.) 

Control freaks will want to use the VIA_OWNERDRAW option so that they can 
draw each individual cell in the value set personally. 
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Table 17-1 Value Set Messages 

Message 

Description 

VM_QUERYITEM 

Returns the contents of the specified ceil: If text, 
sets the PVSTEXT in mp2 to the text value and 
returns the number of bytes copied. If a bitmap or 
an icon, returns the handle of the item (HBITMAP 
or HPOINTER). If a color index or RGB, returns the 
number (ULONG). 

VM_QUERYITEMATTR 

Returns the attributes of the specified cell as a bit 
mask. 

VM_QUERYMETRICS 

If USH0RT1 in mpl is VMAJTEMSIZE, returns the 
size of the cells. If USH0RT1 in mp2 is 
VMAJTEMSPACING, returns the distance 
between each row and column. The values are 
returned as two USHORTS containing the 
requested width and height. 

VM_QUERYSELECTEDITEM 

Returns in MRESULT the row(USHORTI) and the 
column (USH0RT2) of the currently selected item. 

VM_SELECTiTEM 

Selects the specified cell. 

VM_SETITEM 

Sets the contents of the specified cell. mp2 is 
either PSZ, HBITMAP, HPOINTER, a color index, 
or an RGB index, as appropriate to the attributes 
of the cell. 

VM_SETITEiV!ATTR 

Sets the attributes of the specified cell according 
to the bit mask passed in mp2. 

VM_SETMETRICS 

If USH0RT1 in mpl is VMAJTEMSIZE, sets the 
size of the cells. If USH0RT2 in mp2 is 
VMAJTEMSPACING, sets the distance between 
the rows and columns. The dimensions are speci¬ 
fied as width and height USHORTs passed in mp2. 


These calls are really straightforward, making this one of the easiest controls 
to use. You’ll start by setting the individual cell items: 

WinSendDlgltemMsg(hwndDlg, VS_SRS, VM_SETITEM, 

MPFR0M2SH0RT(1,1), MPFR0MP( 

WinGetSysBitmap(HWND_DESKTOP, SBMP_SBUPARROW))); 
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To simplify testing the value set, I used WinGetSysBitmap to illustrate setting 
a value set item to a bitmap. 

SBMP_SBUPARROW even kind of looks like an alien spaceship. (And to think I 
maligned the usefulness of the system bitmaps in Chapter 8!) m 


You may sometimes want to set all the cells at once, which you can do by 
nesting VM_SETITEM messages in a for loop: 


for (i=1;i<=8;i=i+1 ) { 

for (j=l;j<=8;j=j+l) { 

sprintf(txt, "%d", ((i-1)*8)+j); 

WinSendDlgItemMsg(hwndDl g, VS_LRS, VM_SETITEM, 
MPFR0M2SH0RT(i,j),txt); 



Remember, the rows and columns are numbered from 1 to whatever, not 0 to 
whatever. 

If you want to put a bitmap item into a text value set, or any kind of item that 
differs from the default determined by the value set, use VM_SETITEMATTR: 


WinSendDlgItemMsg(hwndDlg, VS_SRS, VM_SETITEMATTR, 
MPFR0M2SH0RT(2,2), 

MPFR0M2SFI0RT ( VI A_C0L0RI NDEX , TRUE)) ; 


WinSendDlgItemMsg(hwndDlg, VS_SRS, VM_SETITEM, 

MP FR0M2SFI0RT (2,2), 

MPFROMLONG(l)); 

The listing shows how this works with each data type. Note that mp2 in this 
message is interpreted appropriately based on the item’s attribute. 

Querying the value set is equally straightforward: 

case WM_COMMAND: 
switch(SHORTlFROMMP(mpl)) { 
case PB_QUERY: 

mr = WinSendDlgItemMsg(hwnd, VS_LRS, 

VM_QUERYSELECTED ITEM, 0,0); 

1 row = SHORTlFROMMR(mr); 

1 col = SH0RT2FR0MMR(mr); 

The listing pops up a message box in response to the Query button. 
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Value Set Callbacks 

Value sets, like all CUA ’91 controls (as discussed in the technical info section 
of the last chapter), generate the WM_CONTROLPOINTER and WM_DRAW- 
ITEM messages. 

Mostly, however, you will respond to the WM_CONTROL message sent by 
your value sets, and mostly to the five shown in Table 17-2. 


Table 17-2 Common Value Set Callbacks 

Galiback 

Description 

VN_ENTER 

User pressed Enter or double-clicked on the item. 

VN_HELP 

Value set received a WM_HELP message. 

VN_KILLFOCUS 

About to lose focus. 

VINLSELECT 

An nondisabled item has been selected. 

VI\l_SETFOCUS 

About to receive focus. 


You may well wonder why the value set will notify you if it receives a 
WMJHELP message when other controls won’t. This, too, seems to reflect the 
increased enlightenment at IBM between the CUA ’89 and CUA ’91 specifica¬ 
tions. (That doesn’t explain why the slider control doesn’t have this callback, 
but hey, nobody ever said IBM was perfect.) 



Normally, mp2 contains a handle to the value set, but in the case of VN_ENTER 
and VNJSELECT it contains the row and column that were selected. 

If the item is disabled it will never generate either a VN_ENTER or a 
VN_SELECT callback. 

You can check out the listing to see how you might interact with the call¬ 
backs, but like the messages, the interaction is very simple. There is one bit 
of code I thought I would draw your attention to: 


case VN_SELECT: 

WinSendDlgItemMsg(hwnd, SP_R0W, SPBM_SETCURRENTVALUE, 
MPFROMSHORT(SHORTlFROMMP(mp2)) ,0) ; 

WinSendDlgItemMsg(hwnd, SP_C0L, SPBM_SETCURRENTVALUE, 
MPFROMSHORT(SH0RT2FR0MMP(mp2 )) ,0); 
return 0; 
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In particular, the MPFROMSHORT(SHORTlFROMMP(mp2)) might cause you 
to spit out your coffee. The SHORT lFROMMP(mp2) gets the selected row 
from mp2, and the outer MPFROMSHORT is just there to get that answer back 
into MPARAM format. It isn’t strictly necessary, but your C compiler may 
emit a few warnings if you don’t convert the value back into MPARAM format. 

Of course, you could always “rephrase” the code: 

row = SH0RTlFR0MMP(mp2); 
col = SH0RT2FR0MMP(mp2); 

WinSendDlgltemMsgfhwnd, SP_R0W, SPBM_SETCURRENTVALUE, 

MPFROMSHORT(row), 0); 


and so on. 

Note also that the code largely doesn’t discriminate between the two value 
sets. The spin buttons will change according to the LRS and the SRS. This was 
just economy of space. If you used something like this in a real program, you 
would usually check SHORT1 of mpl of any WM_CONTROL message to get 
the ID of the control. 

In addition to those five messages, value sets will call back to inform owners 
of drag operations. We can’t cover that here, unfortunately, but the Table 17-3 
is included here for completeness. 


Table 17-3 Drag Operation Callbacks 

Callback 

Description 

VN_DRAGLEAVE 

Received a DM_DRAGLEAVE message. 

VNJDRAGOVER 

Received a DM_DRAGOVER message. 

VNJDROP 

Received a DM_DR0P message. Applies only if 
the item has the attribute set. 

VIAJDROPONABLE 


VN_DROPHELP 

Received a DM_DROPHELP message. 

VNJNITDRAG 

The user pressed the drag button (usually the 
secondary button) and moved the mouse while 
the pointer was over an item that had the 
attribute set. 

VIA_DRAGGABLE 
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Having drag and drop messages built into controls is another CUA ’91 fea¬ 
ture, but one that applies only to certain controls. (It makes little sense with 
a slider.) IBM did not go back and add the capability to the older controls, 
such as the list box, that might benefit from these callbacks. 


The Value Set Sample Program 

As promised, here’s the complete listing for the value set program: 

//define INCL_GPI 
//define INCL_WIN 
//include <os2.h> 

//include "valset.h" 

/* ClientWndProc is a dialog procedure */ 

MRESULT EXPENTRY ClientWndProc(HWND, ULONG, MPARAM, MPARAM); 


. main 

(void) 





HAB 

hab; 

/* 

anchor 

block handle 

*/ 

HMQ 

hmq; 

/* 

message 

queue handle 

*/ 

HWND 

hwndDlg; 

/* 

handles 

to windows 

*/ 

QMSG 

qmsg; 

/* 

message 


*/ 

char 

szClassName[] = 

"Value Sets 

". 



BOOL 

fail = FALSE; 





i nt 

i J : 





char 

txt[1000]; 






hab = Win Initia 1ize(0); 

hmq = WinCreateMsgQueue(hab, 0); 

if (!WinRegisterClass(hab, szClassName, ClientWndProc, 
CS_SIZEREDRAW, 0)) 
fail = TRUE; 

hwndDlg = WinLoadDlg(HWND_DESKTOP, HWND_DESKTOP, 

ClientWndProc , 0, VALSETPROGRAMID, NULL); 

for (i=1;i<=8;i=i+l ) { 
for (j=l;j<=8;j=j+l) { 

sprintf(txt, "%d", ((i-1)*8)+j); 

WinSendDlgItemMsg(hwndDlg, VS_LRS, VM_SETITEM, 
MPFR0M2SH0RT(i,j),txt) ; 
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) 

WinSendDlgltemMsg(hwndDlg, VS_SRS, VM_SETITEM, 
MPFR0M2SH0RT(1,1), MPFR0MP( 

WinGetSysBitmap(HWND_DESKTOP, SBMP_SBUPARROW))); 

WinSendDlgItemMsg(hwndDlg, VS_SRS, VM_SETITEMATTR, 
MPFR0M2SH0RT(2,2), 

MPFR0M2SH0RT(VIA_COLORINDEX, TRUE)); 

WinSendDlgItemMsg(hwndDlg, VS_SRS, VM_SETITEM, 
MPFR0M2SH0RT(2,2), 

M P F ROM LONG(1)) ; 

WinSendDlgItemMsg(hwndDlg, VS_SRS, VM_SETITEMATTR, 
MPFR0M2SH0RT(3,3), 

MPFR0M2SH0RT(VIA_ICON, TRUE)); 

WinSendDlgltemMsg(hwndDlg, VS_SRS, VM_SETITEM, 
MPFR0M2SH0RT(3,3), MPFROMPC 

WinQuerySysPointer(HWND_DESKTOP, SPTR_WAIT, TRUE))); 

WinSendDlgItemMsg(hwndDlg, VS_SRS, VM_SETITEMATTR, 
MPFR0M2SH0RT(4,4), 

MPFR0M2SHORT(VIA_RGB, TRUE)); 

WinSendDlgItemMsg(hwndDlg, VS_SRS, VM_SETITEM, 
MPFR0M2SH0RT(4,4), 

MPFROMLONG(65000)); 

WinSendDlgItemMsg(hwndDlg, VS_SRS, VM_SETITEMATTR, 
MPFR0M2SH0RT(5,5), 

MPFR0M2SHORT(VIA_TEXT | VIA_DISABLED, TRUE)); 

WinSendDlgItemMsg(hwndDlg, VS_SRS, VM_SETITEM, 
MPFR0M2SH0RT(5,5), 

MPFROMP("!")); 

WinSendDlgltemMsg(hwndDlg, SP_R0W, SPBM_SETLIMITS, 

MPFR0ML0NG(8), MPFROMLONG(1)); 

WinSendDlgItemMsg(hwndDlg, SP_C0L, SPBM_SETLIMITS, 
MPFR0ML0NG(8), M P F ROM LON G(1)); 

if ((fail) || (hab==NULLHANDLE) || 

(hmq==NULLHANDLE) || (hwndDlg==NULLHANDLE)) 

WinMessageBox(HWND_DESKTOP, HWND_DESKTOP, 
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"Unable to initialize application.", "ERROR!", 

0, MB_CANCEL | MB_ERR0R); 

el se 

while (WinGetMsg(hab, &qmsg, 0, 0, 0)) 

WinDispatchMsg(hab, &qmsg); 


WinDestroyWindow(hwndDlg); 
WinDestroyMsgQueue(hmq); 

WinTerminate(hab); 

return 0; 

} 


MRESULT EXPENTRY ClientWndProc(HWND hwnd, ULONG msg, MPARAM mpl, 
MPARAM mp2) 

{ 

char message[1000]; 

MRESULT mr; 

USHORT srow, scol , lrow, 1 col ; 

/*event handler*/ 
switch(msg) { 

case WM_COMMAND: 
switch(SHORT1FROMMP(mpl)){ 
case PB_QUERY: 

mr = WinSendDlgItemMsg(hwnd, VS_LRS, 

VM_QUERYSELECTED ITEM, 0,0); 

1 row = SHORTlFROMMR(mr); 

1 col = SH0RT2FR0MMR(mr); 

mr = WinSendDlgItemMsg(hwnd, VS_SRS, 

VM_QUERYSELECTEDITEM, 0,0); 
srow = SHORTlFROMMR(mr); 
scol = SH0RT2FR0MMR(mr); 

sprintf(message, "Long range at %d, %d.\n\ 

Short range at %d, %d", lrow, 1 col, srow, scol); 

WinMessageBoxCHWND_DESKTOP, HWND_DESKTOP, 

message, "Response", 0, MB_0K | MB_INFORMATION); 

return 0; 

} 


case WM_C0NTR0L: 
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switch(SH0RT2FR0MMP(mpl)){ 
case VN_ENTER: 

sprintf(message, "Entry/Dbl click at %d, %d", 

SH0RT1FROMMP(mp2) , 

SH0RT2FROMMP(mp2)); 

WinMessageBox(HWND_DESKTOP, HWND_DESKTOP, 

message, "Selection", 0, MB_0K | MB_INFORMATION); 

return 0; 

case VN_SELECT: 

WinSendDlgItemMsg(hwnd, SP_R0W, SPBM_SETCURRENTVAFUE, 
MPFROMSHORT(SH0RT1FROMMP(mp2)),0); 

WinSendDlgItemMsg(hwnd, SP_C0F, SPBM_SETCURRENTVAFUE, 
MPFROMSHORT(SH0RT2FR0MMP(mp2)),0); 
return 0; 

} 

break; 

case WM_CLOSE: 

WinPostMsg(hwnd, WM_QUIT, 0,0); 
return 0; 



return WinDefD1gProc(hwnd, msg, mpl, mp2); 

} 

As with all the control examples, the header file (VALSET.H) is created by 
the Dialog Editor. 


Conclusion 

The value set is a cool control, and one that reflects IBM’s increasing enlight¬ 
enment. 

It also brings us dangerously close to WPS programming, which has drag-and- 
drop functionality as a hallmark. Part V covers WPS programming basics. 
Before tackling WPS, though, we’ll take a little detour into some interesting 
aspects of OS/2 programming such as graphics, fonts, and threads. 


The fun is just beginning! 




"The teuft-stete £rcm IBM. and Miacecft are here.' 









In This Part .. 


W erein some of the more intriguing aspects of OS/2 
programming are explained: graphics, fonts, 
threads, and those little extra touches, such as installa¬ 
tion folders and objects for your application on the Desk¬ 
top, that make a PM program special. 


In truth, some of these topics could probably fill a sizable 
book on their own, but we’ll tackle each of these tasty 
issues individually. We’ll cut each one up into bite-size 
pieces that not only allow us to savor it, but make it easy 
to digest. 

If you’re getting hungry, you can go get a snack before 
starting these chapters. 



Chapter 18 


A GPI in a Pool of Sharks 


in This Chapter 
The OS/2 interfaces 
The Graphics Programming Interface 
The revenge of the presentation spaces 
A taste of OS/2 printing 
More on bitmaps 


1# ou are already familiar with many of the Win* calls OS/2 uses to facili- 
fjr* tate PM programming, but even so just a small portion of the total Win* 
API is available in OS/2. The purpose of the Win* API, in essence, is to facili¬ 
tate programming with the OS/2 window classes such as the frame window or 
the button window. 

Besides the Win* API, OS/2 also has: 

v* The Dos* API, which manages the non-graphical aspects of OS/2, such as 
threads and dynamic link libraries, as you’ll see in Chapters 20 and 21. 

^ The Dev* API, which interacts with devices, as we’ll touch on briefly in 
this chapter. 

is* The Wp* API, which interacts with the Workplace Shell, as you’ll see in 
the next part of this book. 

v* A host of other smaller APIs for interacting with specific subsystems of 
OS/2, such as the mm* calls for multimedia and the DIVE calls for Direct 
Interface Video Extensions (super-fast PM graphics). (We won’t be cov¬ 
ering mm* or DIVE in this book, alas.) 

With the possible exception of the Dos* API, most of the listed APIs are 
pretty small relative to the Win* API. Comparable in size and scope to the 
Win* API, however, is the Graphics Programming Interface (GPI) API. 
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Gpi* calls handle all the low-level drawing tasks of the Presentation Manager. 
A window of the WC_FRAME class, for example, contains a bunch of Gpi* 
calls to draw straight lines in different colors and thicknesses to create the 
appearance of a frame on the screen. 

If you wanted to create a new control, you would do it in much the same way 
that we have done all of our windows up to this point, except you would call 
the necessary Gpi* functions in response to the WM_PAINT message to cre¬ 
ate the appearance of the desired control. 

In this chapter, we’re going to go back to the BASIC2.C template we created in 
Chapter 9, “An Introduction to Dialogs.” Since we can’t explore the entire GPI 
in depth in this book, we’re going to just get a feel for how the GPI works and 
try to get some sense of the power that lies behind this humongous API. 


The Fit/e GPI Primitives 

The GPI has five fundamental types of graphics that it deals with: line, charac¬ 
ter, marker, area, and image. 



They’re called primitives because they are the basic elements of the GPI that 
can be used to make up far more complex operations. 

This book doesn’t really deal with markers , which are small pictures like bul¬ 
lets or similar glyphs used for notation or emphasis on a larger picture. A 
symbol used in an engineering diagram, for example, might be a marker. 


This book also doesn’t cover areas , which are contiguous portions of a draw¬ 
ing space that the GPI can work with to create patterns and filled-in polygons. 

The next chapter deals with characters in a little more depth than we did 
originally in Chapter 4, Getting Your Feet Wet and GUI, where we just used 
WinDrawText. 


That leaves lines and images for this chapter and, as lines are simpler, we’ll 
start with those to get an idea of how many of the GPI functions work. 
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A Line Without ParnUei 


Take a look at the following code: 


GpiMove(hps, &pt); 
GpiLine(hps , &pt2); 



Assume that hps is a handle to a presentation space and that pt and pt2 are 
POINTL types, containing an x and a y to designate a location. This code will 
draw a line from pt to pt2. 

This code will actually work, by the way: Just plug it into the WM_PAINT case 
handler in between the WinFillRect and the WinEndPaint calls. (You’ll have 
to give meaningful values to pt and pt2, of course.) : 


General: LONG GpiMove(HPS hps, PPOINTL pptl) 
As Used: GpiMoveChps, &pt); 

General: LONG GpiLine(HPS hps, PPOINTL pptl) 
As Used: GpiLineChps, &pt2); 


These two little lines of code tell us a lot about the GPI. First of all, they tell 
us that the GPI functions must use some kind of “pointer” to indicate where 
the next drawing function should begin. 

We could reduce the code to just: 


GpiLine(hps, pt2); 

From that, we could probably ascertain where the pointer begins when a pre¬ 
sentation space is first created. 

What else do these lines tell us? Well the line is drawn in a color, isn’t it? And 
with a particular width and as one solid line, as opposed to a broken line or 
some other kind of pattern. 

From this we can guess that either the GPI limits us to drawing lines of a cer¬ 
tain style, color, and thickness, or that there are defaults for these attributes 
that can be queried and set independently of any actual drawing action. 


Line styling 

The truth of the situation is the latter: Every presentation space contains a 
number of drawing settings that determine what a particular primitive is 
going to look like. 
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You can, for example, set the color that the five primitives are going to be 
drawn in using the GpiSetColor function: 

General: BOOL GpiSetColorCHPS hps, LONG color): 

As Used: GpiSetColor(hps, CLR_DARKCYAN); 


The basic color possibilities are: 

CLR_FALSE CLR_TRUE CLR_DEFAULT 

CLRJIHITE CLR_BLACK CLR_BACKGROUND 

CLR_BLUE CLR_RED CLR_PINK 

CLR_GREEN CLR_CYAN CLR_YELLOW 

CLR_NEUTRAL CLR_DARKGRAY CLR_DARKBLUE 

CLR_DARKRED CLR_DARKPINK CLR_DARKGREEN 

CLR_DARKCYAN CLR_BR0WN CLR_PALEGRAY 




These settings are largely self-explanatory. Among those that aren’t, think of 
CLR FALSE as black and CLR_TRUE as white. CLR_NEUTRAL is some color 


PM colors 


We've brushed up against PM's system of 
coloring screen items a number of times, but 
never really delved into the whys and where¬ 
fores of it. 

It's not practical to expend a lot of energy 
exploring the coloring scheme employed by 
PM when so many other more worthy topics 
await us, but a little explanation of the two 
basic kinds of coloring schemes is in order. 

The first coloring scheme, called a logical 
colortable, is the one used by default and the 
one for which the above values are meaning¬ 
ful. A logical color table is basically like a 
giant array where each element of the array 
specifies a particular color. Often, these ele¬ 
ments can be referred to by their purpose 
such as "button color" or "frame color" 
instead of by some numeric value that 
expresses the physical value used to create 
the color on the screen. 


They can also be used, as above, to express 
official designations for colors. Your monitor 
may be capable of producing thousands or 
millions of colors, but CLR_RED represents 
the "official" red to be used. 

The other scheme (called RGB, for Red-Green- 
Blue) is where the actual numbers are used. 0 
is black, the maximum value is white, and the 
intervening values are mixtures of red, green, 
and blue that create all the other possible col- 


Obviously, this scheme gives us more variety, 
but it also makes conformity a little more diffi¬ 
cult. 

To research further, investigate the GpiCre- 
ateLogColorTable function in the Warp Tool¬ 
box on-line help. 
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that contrasts with CLRJBACKGROUND, as is CLR_DEFAULT. CLR_DEFAULT 
can be changed through a call to GpiSetDefAttrs. 

Besides colors, the line style can be altered. This is done through a call to 
GpiSetLineType: 

General: BOOL GpiSetLineType(HPS hps, LONG type); 

As Used: GpiSetLineType(hps, LINETYPE_DASHDOUBLEDOT); 

The possible line types are: 


LIN ETY P E_D0T 
LINETYPE_DASHDOT 
LIN ETY P E_LONGDASH 
LIN ETY P E_S0 LID 
LINETYPE_ALTERNATE 


LINETYPE_SHORTDASH 
LINETYPE_D0UBLEDOT 
LI NETYPE_DASHDOUBLEDOT 
LINETYPE_INVISIBLE 


These styles tell you exactly how a line constructed by GpiLine (or another 
line drawing function) will be drawn. If you use LINETYPEJDOT, the line will 
be made up of small dots with spaces in between them, as opposed to LINE- 
TYPE_SOLID, where every pixel between the two points will be drawn. 


LINETYPE_ALTERNATE is probably the only obscure member of the cast. 
With this style, every other pixel is drawn. When you draw a black line with 
this style, for example, it appears gray. 


k 



We’ve experienced a similar effect several times throughout the book with 
the half-tone style. This alternating pixel style can convey the meaning that a 
control is disabled. In a line, it can similarly convey that the line is less 
important than solid lines, or somehow nonfunctional. 


The unruly s^uigyte 

Of course, it would be tedious to draw a dodecahedron (a twelve-sided poly¬ 
gon) using only GpiMove and GpiLine. After the initial GpiMove, it would take 
twelve calls to GpiLine to create such a figure. 

That’s why the GPI provides a function called GpiPolyLine: 

General: LONG GpiPolyLine(HPS hps, LONG count, PPOINTL p) 

As Used: GpiPolyLine(hps, 99, pt+1); 

GpiPolyLine is like a connect-the-dots function. You pass it the dots as an 
array of POINTLs, telling it how many dots you passed with the second para¬ 
meter. The function draws a line from the first point passed to the second, 
then from the second point to the third, and all the way through the array. 
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If you know your geometry, you can create all manner of shapes with this 
function, including shapes that give the appearance of roundness. 

In other words, you can even draw a circle out of a bunch of tiny lines. You 
could also use the GpiFullArc function to create a circle, but there are many 
more complex shapes than circles that you can draw if you know what you’re 
doing. 


If you’re like me, though, you probably whined to your parents that nobody 
ever uses geometry in real life, and promptly forgot what little you managed 
to learn in geometry class. 


Because of this, and because I have a more literary than mathematical 
nature, the big code example for this chapter is—a squiggle: 


GpiErase(hps ) ; 

pt = ( PPOINTDmal 1 oc( 100 * si zeof ( POINTL)) ; 


if (pt!=NU LL) 

for |i =0; i <100; i = i +1) { 
pt[i].x = ranch) % rcl.xRight; 
pt[i].y = ranch) % rcl.yTop; 


GpiSetCol or(hps , CLR_DARKCYAN); 
GpiMove(hps , pt); 

GpiPolyLine(hps , 99, pt+1); 


Yes, Fm actually going to explain the literary significance of the squiggle later 
in this chapter. 



This shows a pretty usual example of GpiPolyLine. Note that it uses GpiMove 
on the first entry in the array, and then passes the array from the second 
entry. 

To get a closed polygon, you make the last entry in the array the same as the 
first. 

You may want to play around with the number of points actually drawn. It 
can be quite surprising how fast PM will draw these lines. 
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Maintaining \lour Image: A Bitmap 
Reprise 

We experimented briefly with bitmaps in Chapter 8, “Bitmaps, Icons, and 
Pointers,” as an introduction to resources. In that chapter we used the 
handy-dandy WinDrawBitmap function to display a bitmap on screen. 

As useful as the WinDrawBitmap function is, though, it pales in both power 
and complexity when contrasted with the awesome GpiBitBlt. (Okay, maybe 
I’m pumping this function up a little bit here—but it’s pretty cool!) 

GpiBitBlt is a little intimidating both to look at and to use, but it gives us a 
chance to brush up on some topics that we’ve been avoiding until now. 

General: LONG GplBitBlt(HPS target, HPS source, LONG count, PPOINTL 
points, LONG mix, ULONG opts); 

As Used: GpiBitBlt(hps , wd->hpm, 3, pt, ROP_SRCINVERT, B B 0_IGNORE); 

In short, GpiBitBlt takes a piece of the source presentation space (second 
parameter) and transfers it to some portion of the target presentation space 
(first parameter), mixing overlapping colors according to the fifth parameter. 

The areas of the presentation spaces are described in the array of POINTLs 
passed as the fourth parameter. The first two POINTLs passed indicate which 
area of the target HPS is going to be written over. 

If the target area is the same size as the desired portion of the source presen¬ 
tation space, only three POINTLs are specified in the array. The third POINTL 
gives the origin of the desired bitmap to copy in the source presentation 
space. 



Although GpiBitBlt may make you think of a bacon, lettuce, and tomato sand¬ 
wich, the bit is actually an abbreviation for block transfer. A block transfer is 
the technical name for the process of moving a bitmap from one area of mem¬ 
ory to another. Less formal terminology for this is bit blitting or sometimes bit 
blasting. 



One potential use for this function would be to create a presentation space 
full of bitmaps to be used in a game. When you needed a bitmap, you would 
just copy it out of your presentation space and display it on the screen’s pre¬ 
sentation space. Figure 18-1 shows how this might work. 
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Figure 18-1: 
A bunch 
of bitmaps 
to bit. 
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Bitmap Space 


Keep in mind that this technique’s performance, while fast relative to some 
others you might use, is pretty poor relative to the speedy kind of screen per¬ 
formance you can get under an operating system like DOS, where programs 
can directly access the screen. 

That’s why the DIVE (Direct Interface Video Extensions) exist for OS/2—to 
enable multimedia and games programs to have high performance video 
output. 




Chapter 18 A GPI in a Pool of Sharks 253 


Unlike Window’s WinG interface, DIVE is actually part of the operating sys¬ 
tem, and should therefore be portable to future versions of the OS, including 
OS/2 for the PowerPC. 


However, GpiBitBIt also allows you to stretch the bitmap copied from the 
source to the target. So, you could take a 10-by-10 area of pixels out of your 
source bitmap and stretch it to fill the entire target area. All you have to do is 
specify the right values for the four POINTLs. 


When you do this stretching, you must specify one of the following options as 
the last parameter of GpiBitBIt: BBO_OR, BBO_AND, or BBOJGNORE. These 
three options are applied when a bitmap is compressed. 

In order to turn a 10-by-10 bitmap into a 5-by-5 bitmap, five rows and five 
columns of the bitmap must be removed. If you specify BBOJGNORE, the 
GpiBitBIt function just removes them—nothing else is done. (This is the 
usual option for color bitmaps.) 


If you specify BBO_AND, a row (or column) that has been eliminated will be 
logically ANDed with an adjacent row. What that means is that if a pixel in the 
eliminated row is white and a pixel in the adjacent row is white, the bit 
remains white in the compressed version. If either pixel is black, the pixel will 
be black in the compressed version. This is the usual option for a mono¬ 
chrome bitmap where the picture is black on a white background. 

If you specify BBO_OR, the same process is applied. If either pixel is white, 
the final pixel will come out white. Both pixels must be black in this case for 
the compressed pixel to come out black. This is the usual option for a mono¬ 
chrome bitmap where the picture is white on a black background. 


I have no idea what you would do for a bitmap of a zebra. 



One other option may be specified. Normally, you draw a bitmap with the 
idea that the colors are physical values, to be reproduced exactly whenever 
drawn. 

It is possible, however, to design a bitmap using a kind of paint-by-number 
approach—draw this area in color 1, draw this area in color 2, and so forth. 
(You could use this to create some pretty cool effects, if you could get 
GpiBitBIt to draw those colors according to a palette that you changed based 
on certain program events.) If you’ve created a bitmap with this in mind, you 
would use the BBO_PAL_COLORS option. 



« Ctf. 
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Bitmaps: Great Mixers 

The fifth parameter of GpiBitBlt, mix, is interesting in and of itself, so let’s 
take a moment to look at it. 

A bitmap can be copied from the source to the target so that it appears on 
the target exactly the same way it appears in the source. A good thing, one 
would think; however, a bitmap can also be copied to take into account two 
other factors. These factors are the current pattern for the (target) presenta¬ 
tion space and what is already on that presentation space. 

So if we impose a picture of a ball on the squiggle created in the previous sec¬ 
tions, we can have the ball appear and completely obscure the squiggle, or 
we can have the squiggle show through the ball, or we can set a pattern to 
show through the ball, or mix these options in any possible fashion. 

The mix is an eight-bit integer formed by deciding what should happen when 
the various parts of the pattern, the source, and the target are combined. 
Take a look at the following example: 

Pattern: 00001111 
Source: 00110011 
Target: 11110000 

Say you wanted to create a mix pattern where the source came out on the 
target exactly as it appeared in the source. That’s an easy mix to create—you 
just copy over the source pattern: 

Pattern: 00001111 
Source: 00110011 
Target: 11110000 
Mix : 0 0 1 1 0 0 1 1 

You then convert the binary number 00110011 to a decimal (51) and use that 
as the mix. 



The technical name for what I’ve been calling a mix is raster operation. 

(Raster is often used synonymously with bitmap.) 

What if you wanted to copy over the source, but also leave what was on the 
target? You would go through the bits from left to right and leave on anything 
that was a 1 in both the source and the target: 
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Pattern: 

0 
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1 

1 
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1 

Source: 
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T a rget: 
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0 

Mix : 

1 
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1 

1 

0 

0 

1 
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Then you’d convert the result to a decimal (243) and use that as the mix. 

GpiBitBlt comes with the following ROP_* codes defined (where ROP stands 
for raster operation, and is a predefined mix): 


ROP^SRCCOPY 
R0P_SRCINVERT 
ROP_NOTSRCERASE 
R0P_PATC0PY 
ROP_DSTINVERT 


ROP_SRCPAINT 
ROP_SRCERASE 
R0P_MERGEC0PY 
ROP_PATPAINT 
ROP_ZERO 


ROP_SRCAND 
R0P_N0TSRCC0PY 
ROP_MERGEPAINT 
ROP_PATINVERT 
R0P_0NE 


In my experience, it’s not really worthwhile to explain what these codes do, 
as you can learn far better by trying them out yourself. To get a good feel for 
them, though, you need to be able to set the current pattern: 


General: BOOL GpiSetPattern(HPS hps, LONG pattern) 


You can use PATSYM_VERT as the second parameter (it makes the pattern a 
series of vertical lines), or look up the GplSetPattern function in the GPI on¬ 
line help supplied with the Toolkit to try out different pattern types. 



One of the reasons I’m not spending a lot of time on this function or on the 
subject of bitmap mixing is that bitmap mixing is really clear for mono¬ 
chrome bitmaps: The color is either black or white. If you specify that you 
want a bitmap to be drawn with ROP_SRCINVERT, all the black on your 
bitmap will be turned to white, and all the white will be turned to black. 


What happens with a color bitmap is not as simple, and consequently, not as 
useful, as we’ll see in the next section. 


Presenting: TiVo Presentation Spaces 

We haven’t even covered the most interesting aspect of GpiBitBlt, which is: 
We have two presentation spaces! Where do we get that second presentation 
space and how do we get our bitmap into it? Any sophisticated PM program is 
going to create multiple presentation spaces, so this is a good topic to look at. 

First, let s define what a presentation space really is: A presentation space is 
a structure in memory capable of receiving drawing commands. Nobody ever 
sees a presentation space. 



256 Part IV Polish and Panache 


We’ve obscured that fact somewhat, because we’ve been using the kind of 
presentation space that automatically gets returned from WinBeginPaint, and 
that is always associated with the screen. 

However, the presentation space is (in theory, anyway) a distinct and sepa¬ 
rate entity from the device that ultimately displays the picture created on the 
presentation space. 

Another way of looking at it is: A presentation space is kind of like a plate 
used in lithography. When artists create a lithograph, they start by creating a 
plate that describes the image that they want to appear. The lithograph itself 
is printed from the plate. The plate itself is not the object, the lithograph is. 

When you draw on a presentation space, you’re creating a lithographic plate. 
When you associate the PS with a device, you’re creating a lithograph— 
something for the user to view. 

PM has, in fact, three types of presentation spaces, each with different uses: 

The Cached Micro-Presentation Space is returned by WinBeginPaint when 
no PS is specified in the second parameter. The Cached Micro-PS is 
always associated with the display screen. It is created and destroyed 
generally within one WinBeginPaint/WinEndPaint block (The kind we’ve 
been using all along). 

The Micro-Presentation Space can be returned by GpiCreatePS. The 
Micro-PS is always associated with exactly one device. 

The Normal Presentation Space can also be returned by GpiCreatePS. 
The Normal PS can be associated with more than one device. 

We need a PS for our bitmap, if we’re going to use GpiBitBlt. We can’t use a 
Cached Micro-PS. A Normal PS, while obviously pretty cool, is probably 
overkill for our purposes. 

Remember, it’s a bitmap. We want to associate it with a single device: mem¬ 
ory. The Micro-PS would seem best suited to our purposes. Let’s look at Gpi¬ 
CreatePS. 


GpiCreatePS: The name sa^s it alt? 

General: HPS GpiCreatePS(HAB hab, HDC hdc, PSIZEL size, ULONG opts) 
As Used: wd->hpm = GpiCreatePSGiab, wd->hdc, &size, 

PU_PELS | GPIF_DEFAULT | GPIT_MICRO | GPIA_ASSOC); 
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We have a bit of work to do before we get to GpiCreatePS. We need the 
anchor block handle, an HDC (a handle to a device context), a size for the PS 
(SIZEL is a structure containing two LONGs, cx and cy), and we have to figure 
out which options to use. 

Getting the anchor block is easy enough. WinQueryAnchorBlock does that: 

General: HAB WinQueryAnchorBlock(HWND hwnd); 

As Used: hab = WinQueryAnchorBlock(hwnd); 

That’s part of the goofiness that is the anchor block handle. PM doesn’t really 
need it—it could always figure it out. But what about a device context? What 
the heck is that, anyway? 

A device context is like the lithographer’s paper. It is the medium on which 
the presentation space is going to be displayed, printed, plotted, or other¬ 
wise revealed to the user. 


General: HDC DevOpenDC(HAB hab, LONG type, PSZ devinfo, LONG count, 
PDEVOPENDATA devdata, HDC comp); 

As Used: wd->hdc = DevOpenDC(hab, 0D_MEM0RY, , 0, NULLHANDLE, 

0 ); 

Relax. It’s not as bad as it looks. Anchor blocks we know about. The type tells 
DevOpenDC what kind of device it is. We’ll use OD_MEMORY, because we 
simply want to write the bitmap to RAM so that we can copy it out later with 
GpiBitBlt. 

The “*” in the third parameter says that we have no special device informa¬ 
tion to give DevOpenDC. We really don’t care about the rest of the parame¬ 
ters—they’re for use with devices more complex than memory—so we can 
make them 0 and NULLHANDLE. 

Back to GpiCreatePS: If a presentation space is to be immediately associated 
with a specific device (a Micro-PS as opposed to a Normal PS), we don’t need 
to specify a size for the PS. If we specify 0, GpiCreatePS will use default values 
to create the PS. 


That leaves us with only the options to wade through. There are four cate¬ 
gories of options. The first is the units by which the presentation space is 
going to be entered. 



Remember that a presentation space is not an actual output device, so it 
doesn’t need to be measured in pixels. If you like, you can create a PS that is 
measured in fractions of an inch (PUJLOENGLISH indicates 1/10th of an inch, 
PU_HIGHENGLISH indicates l/100th of an inch) or even twips (PU_TWIPS), 
which are l/1440th of an inch! 
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It’s also interesting to note that you can specify PU_ARBITRAR. If you want to 
create a presentation space that’s 100 by 100, and you don’t care 100 by 100 
what, you can do so. 

The GPI contains many elaborate features for translating these systems from 
one to the other. 

For our purposes, PU_PELS seems the obvious choice. (Pels and pixels are 
synonymous.) We’re using a bitmap that is going to have a specific pel size, 
so it makes sense that we should specify PU_PELS. 

GpiCreatePS allows you to specify whether you are going to interact with the 
PS using LONG (GPIF_LONG) or SHORT (GPIF_SHORT) integers. (You would 
use LONG if you were working with a very large picture or a picture that you 
didn’t know the size of.) We don’t care particularly, so GPIF_DEFAULT is fine 
for our purposes. 

The next set of options is either GPlT_NORMAL, to create a Normal presenta¬ 
tion space, or GPITJV1ICRO, to create a Micro presentation space. We want 
the latter. 

The last set of options determines whether or not the PS must be associated 
with a device context in order to be used. This has to be GPIA_ASSOC for a 
Micro-PS like ours. GPIA_NOASSOC is available as an option for a Normal PS. 

Well, that took a lot of explanation for one little call. And all that just to get a 
PS for our bitmap, which we haven’t even done yet. 

wd->hpm = GpiCreatePS(hab , wd->hdc, &size, 

PU_PELS | GPIF_DEFAULT | GPIT_MICR0 | GPIA_ASS0C); 

Setting the bitmap into the presentation space is trivial, once you have the 
presentation space: 

General: HBITMAP GpiSetBitmapCHPS hps, HBITMAP hbmp); 

As Used: GpiSetBitmap(wd->hpm, wd->hbmp); 

This sets the bitmap passed as the second parameter into the presentation 
space passed as the first parameter. Used consecutively, GpiSetBitmap will 
replace the last bitmap set into the PS with the new one. 

Closing, code 

After creating a device context, presentation space, and bitmap, make sure 
you destroy them at the end of the program: 
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GpiDestroyPS(wd->hpm); 

DevCloseDC(wd->hdc); 

GpiDeleteBitmap(wd->hbmp); 

Notice that you destroy the PS before closing the device context. 


/ iot/e it When a pirn c&mes together 

This may not have been the most exciting chapter for you. We spent a long 
time exploring presentation spaces and bitmaps just to understand a few 
lines of code and some concepts which, while very important, are challenging 
and reveal only the surface of a much deeper subject. 

The payoff of this chapter is understanding a complete, albeit simple pro¬ 
gram that incorporates many of the major concepts we’ve touched on 
throughout the book. 

Here are some things to keep in mind while looking at this program: 

u* The window data is stored, using WinSetWindowPtr, in a structure 
called WINDOWDATA declared at the beginning of the program. This 
approach is preferable to using static local variables, because of the 
capability of window procedures to be re-entrant. 

u* A timer is used to create the bouncing ball effect. The ball moves, yet 
the window menu is accessible and the program does not tie up the rest 
of WPS. 

v* The squiggle is drawn once at the beginning of the program, and later 
only if the window is resized, shown, or activated. 

v* ROP_SRCINVERT is used to cause the bitmap to be drawn as the inverse 
of what it is. I used a 32-by-32 bitmap of a pink ball. Inverted, the pink 
ball comes out green! This example illustrates the point I was making 
about the problems of bitmap mixing when dealing with color. 

v* ROP_SRCINVERT lets the squiggle show up through the ball, although it 
shows up inverted. 

Drawing the bitmap inverted twice in the same position erases the 
bitmap. By drawing the bitmap inverted in its previous position, the 
bitmap is erased and the screen restored to its original state. The bitmap 
is then moved slightly and drawn again. 

Here’s the complete source for GPI.C: 

#define INCL_GPI 
#define INCL_WIN 
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#include <os2.h> 

#include <string.h> 

#include "GPI.h" 

MRESULT EXPENTRY ClientWndProc(HWND, ULONG, MPARAM, MPARAM); 

#define APPNORMAL 0 
#def ine INITFAILURE -1 
#define USERQUIT -2 

typedef struct { 

HPS hpm; 

HDC hdc; 

HBITMAP hbmp; 

BOOL first; 

int px, py, ox, oy; 

} WINDOWDATA; 

typedef WINDOWDATA *PWINDOWDATA; 


int main (void) 

{ 

HAB hab; /* anchor block handle */ 

HMQ hmq; /* message queue handle */ 

HWND hwndFrame, hwndClient; /* handles to windows */ 

QMSG qmsg; /* message */ 

char szClassName[] = "Juster"; 

char szWindowTitle[] = "To The Vector Go The Spoils"; 
ULONG flFrameOpts = FCF_STANDARD; 

ULONG appState = APPNORMAL; 

hab = Winlnitialize(0); 

hmq = WinCreateMsgQueue(hab, 0); 

if (!WinRegisterClass(hab, szClassName, Cli entWndProc , 
CS_SIZEREDRAW, 4)) 
appState = INITFAILURE; 

hwndFrame = WinCreateStdWindow(HWND_DESKTOP, WS_VISIBLE, 

&flFrameOpts, szClassName, 
szWindowTitle, 0L, 0, 

GPIPROGRAMID, 

&hwndClient); 


WinStartTimer(hab, hwndClient, 0, 0); 
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if ((appState==INITFAILURE) || (hab==NULLHANDLE) || 

(hmq==NULLHANDLE) || (hwndFrame==NU LLHANDLE)) 

WinMessageBox(HWND_DESKTOP, HWND_DESKTOP, 

"Unable to initialize application.", "ERROR!", 

0, MB_CANCEL | MB_ERR0R); 

el se 

while (appState==APPNORMAL) { 

while (WinGetMsg(hab, &qmsg, 0, 0, 0)) 

WinDispatchMsg(hab, &qmsg); 

if (WinSendMsg(hwndClient, WM_COMMAND, 

MPFR0M2SH0RT(CMD_VERIFY, 0), 0) != MBID_CANCEL) 
appState = USERQUIT; 

if (qmsg.hwnd == NULLHANDLE) /^system shutdown */ 

if (appState != USERQUIT) WinCancelShutdown(hmq, FALSE); 


WinDestroyWindow(hwndFrame); 
WinDestroyMsgQueueC hmq); 

WinTerminate(hab); 

return 0; 

} 


MRESULT EXPENTRY ClientWndProc(HWND hwnd, ULONG msg, MPARAM mpl, 
MPARAM mp2) 


HPS hps; 
RECTL rcl ; 
ULONG cmd; 
PPOINTL pt; 
POINTL ptl ; 
i nt i ; 

SIZEL size; 
HAB hab; 
PWINDOWDATA wd; 


/*event handler*/ 
switch(msg) { 


case WM_CREATE: 

wd = (PWINDOWDATA)cal 1oc(1, sizeof(WINDOWDATA)); 
WinSetWindowPtr(hwnd, 0, wd); 
hab = WinQueryAnchorBlock(hwnd); 
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wd->hdc = DevOpenDC(hab, 0D_MEM0RY, 0, NULLHANDLE, 0); 

size.cx = 0; 
size.cy = 0; 

wd->hpm = GpiCreatePS(hab, wd->hdc, &size, 

PU_PELS | GPIF_DEFAULT | GPIT_MICRO | GPIA_ASSOC); 

wd->hbmp = GpiLoadBitmap(wd->hpm, 0, THEDOT, 0,0); 

GpiSetBitmap(wd->hpm, wd->hbmp); 
wd->first = TRUE; 

wd->px = 4; wd->py = 4; wd->ox = 1; wd->oy = 1; 
return 0; 

case WM_SIZE: 

case WM_SH0W: 

case WM_ACTIVATE: 

wd = WinQueryWindowPtr(hwnd, 0); 

wd->first = TRUE; 

WinlnvalidateRect(hwnd, NULL, TRUE); 
return 0; 

case WM_PAINT: 

wd = WinQueryWindowPtr(hwnd, 0); 

hps = WinBeginPaint(hwnd, NULLHANDLE, NULLHANDLE); 

WinQueryWindowRect(hwnd, &rcl); 

if (wd->first) { 

GpiErase(hps); 

pt = ( PPOINTDmal 1 oc( 100 * si zeof ( POINTL)); 
if (pt!=NULL) 

for (i =0; i < 100; i = i +1) { 
pt[i].x = rand() % rcl.xRight; 
pt[i].y = rand() % rcl.yTop; 

} 

GpiSetColor(hps, CLR_DARKCYAN); 

GpiMove(hps, pt); 

GpiPolyLine(hps, 99, pt+1); 

} 

pt = ( PPOINTDmal 1 oc(4 * si zeof ( POINTL)); 
if(!wd->first) { 

pt[0].x = wd->ox; /* target */ 

pt[0].y = wd->oy; /* origin */ 

ptE1].x = wd->ox+32; /* target */ 

ptE1 ] -y = wd->oy+32; /* extent */ 
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pt[2].x = 0; /* source */ 

pt[2].y = 0; /* origin */ 

GpiBitB11(hps, wd->hpm, 3, pt, ROP_SRCINVERT, BBO_IGN0RE); 

if ((pt[0].x <= rcl.xLeft) || (pt[0].x >= (rcl.xRight- 
32))) 

wd->px = -wd->px; 
wd->ox = wd->ox + wd->px; 

if ((pt[0].y <= rcl.yBottom) || (pt[0].y >= (rcl.yTop- 
32))) 

wd->py = -wd->py; 
wd->oy = wd->oy + wd->py; 

} 

pt[0].x = wd->ox; /* target */ 

pt[0].y = wd->oy; /* origin */ 

pt[l].x = wd->ox+32; /* target */ 

pt[l].y = wd->oy+32; /* extent */ 

pt[2].x = 0; /* source */ 

pt[2].y = 0; /* origin */ 

GpiBitBlt(hps, wd->hpm, 3, pt, R0P_SRCINVERT, BB0_IGNORE); 
wd->first = FALSE; 

WinEndPaint(hps ); 
return 0; 

case WM_TIMER: 

WinlnvalidateRect(hwnd, NULL, TRUE); 
return 0; 

case WM_COMMAND: 

switch(SH0RT1FROMMP(mpl)) { 
case CMD_VERIFY: 
cmd = MB ID_N0; 

/* if (data_modified) */ { 

cmd = WinMessageBox(HWND_DESKTOP, hwnd, 

"Do you want to save your work before exiting?", 

"Query", 0, MB_YESNOCANCEL | MB_QUERY); 

/* if cmd==MB_YES save_data */ 

} 

return (MRESULT)cmd; 

/* case CMD_OTHERCOMMANDS: */ 
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} /* end WM_COMMAND messages */ 
break; 

case WM_DESTROY: 

wd = WinQueryWindowPtr(hwnd , 0); 

GpiDestroyPS(wd->hpm); 

DevCloseDC(wd->hdc); 

Gpi Del eteBitmap(wd->hbmp); 
free(wd); 
return 0; 

} /*end event handlers */ 
return WinDefWindowProc(hwnd, msg, mpl, mp2); 


Here’s the header file, GPI.H: 


#def ine 

GPIPROGRAMID 

1000 

#define 

CMD_HELP 

1001 

#define 

CMD_VERIFY 

1002 

#def ine 

MID_FIL E 

2000 

#define 

C M D_ FILEOPEN 

2001 

#define 

THEDOT 

10000 


And here’s the resource file, GPI.RC: 

#i nclude <os2.h> 

#include "gpi.h" 

ICON GPIPROGRAMID dotnline.ico 

BITMAP THEDOT thedot.bmp 

MENU GPIPROGRAMID 
BEGIN 

SUBMENU "~Fi1e",MID_FILE 
BEGIN 

MENUITEM "~0pen\tCtrl+0",CMD_FILEOPEN 
MENUITEM SEPARATOR 
END 
END 

ACCELTABLE GPIPROGRAMID 
BEGIN 

VK_FI, CMD_HELP, VIRTUALKEY, HELP 

END 
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Note that this is identical to BASIC2.RC (from Chapter 9) except for the ICON 
and BITMAP definitions at the top. For the icon, I drew a straight line with a 
pink ball superimposed on it. For the bitmap, I drew a 32-by-32 pink circle. 

Figure 18-2 shows the results. 





The inspiration for GPI.C 


In the ' 60 s, author Norman Juster wrote a 
story called "The Dot and the Line" concern¬ 
ing the efforts of one straight line to woo a 
frivolous dot taken with an unruly squiggle. 
(The dot prefers the squiggle because the 
line is too boring, too straight, too stiff.) 

The line ultimately emerges victorious by 
using intense discipline to form elaborate 


geometrical designs that the squiggle cannot 
compete with. 

The great animator, Chuck Jones, won an 
Academy Award for his cartoon rendition of 
the story. 
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Conclusion 

By far the most useful information in this chapter concerns the presentation 
spaces. Master them and you have mastered OS/2 in a very real way. 

This statement implies that the information on drawing lines and bitmaps is 
somehow less important. It is. 

Consider: The bulk of all applications written are going to be satisfied by 
using dialogs and controls, with very little call to use the graphics features of 
PM. At least 90% of all applications are largely concerned with interacting 
with databases. 

What if you’re in the percentage that needs graphics? Well again, for most of 
us, it is far more efficient to buy a business graphics library than to build our 
own. But if you really want to build one, you’re best served by purchasing a 
book concerned with nothing but the OS/2 GPL It’s that big a topic. 

If you’re interested in games programming or multimedia, again, your special 
needs would best be met by studying DIVE, and not fooling around with 
GpiBitBlt. Apart from a few straightforward calls, DIVE allows you to use the 
same programming techniques used by DOS games and multimedia program¬ 
mers. 

So, this chapter was mostly concerned with giving you a rough feel for the 
GPI, not with turning you into a graphics wizard. If you can draw a line and 
place a bitmap, give yourself an “A” and move on. 

The next chapter will conclude our exploration of the GPI by showing feats 
that you can perform with characters through various GPI calls. 



Chapter 19 

Fancy Fonts 


In This Chapter 
The art of fonts 
Requesting a font 
Font metrics 
p Using fonts 

Font special effects 


M Y ou ^ now that the Toolkit comes with a tool called the Font Editor? 
#*^(A font, as you doubtless know, is a specific set of characters sharing a 
common style.) 


As an experiment, you might try creating a font—a formidable task, as you 
will quickly discover. You might try just editing the default font that the Font 
Editor starts with. But even subtle changes in a letter can make it look not 
right, can make it stick out like a sore thumb, and can even make it illegible. 


So perhaps we should refine our understanding of fonts a little bit. To create 
a font is to create a work of art. We could postulate that the most practical of 
fonts have as a requirement only that the reader not really notice them. That 
is, the font communicates letters without drawing attention to itself. We 
might consider OS/2’s system fonts to be in this category. 

But strictly speaking, that isn’t really possible: Any font, even OS/2’s system 
fonts, communicates something to the reader, no matter how unobtrusive it 
tries to be. Imagine if this book were printed using one of OS/2’s system 
fonts. You would have put it down as soon as you picked it up. When you 
read a book, you expect to see a book font. 


If the book had been written entirely in this font, you would have 
thought it amateurish, even though there's nothing particularly diffi¬ 
cult to read about this font. Monospace fonts, although useful for 
illustrating code, make text appear as if it were written for a first 
grade reading primer. 
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So, now that we have sufficient respect for the art of font design, we can 
leave that subject to the artists and professionals who understand it. 

As programmers, we have to know how to select and use the available fonts 
so that the information we display to the user looks professional. OS/2 comes 
with an assortment of fonts that we can use in creating programs. 

Strictly speaking, if you’re writing a program that other people are going to 
install on their Warp systems, the only thing you can be certain of is that the 
OS/2 system fonts are there. 

Most of this chapter is going to presume that the standard OS/2 fonts 
(Courier, Helvetica, and Times New Roman) are installed on the system, but 
we’ll look at what happens when you try to use a font that isn’t there. 


Bitmaps Versus Vectors 

There are two ways to describe fonts: as bitmaps or as vectors. 

Bitmap (or raster ) fonts store characters as bitmaps—collections of dots— 
just as the OS/2 logo bitmap (which we looked at in Chapter 8) and the dot 
bitmap (from the last chapter) are stored. 

A vector font stores characters in terms of the actual strokes needed to create 
the character. Instead of a collection of dots, a vector font contains instruc¬ 
tions for drawing a number of lines at certain angles and at certain distances 
relative to other lines. 

A vector font takes considerably more time to draw than a bitmapped font, as 
you might imagine. A bitmapped font merely needs to be blitted onto the 
screen, while a vector font must be interpreted. In addition, bitmapped fonts 
are specifically designed for a particular device (like the screen). They might, 
in some situations, look better than vector fonts, which must be described in 
abstract terms that are adjusted to each device they are displayed on. 

So why use a vector font at all? Well, since vector fonts are described in 
terms of how they are drawn, you can scale, rotate, or otherwise create spe¬ 
cial effects that are impossible to get with a bitmapped font. 
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Drawing Text the Hard Way 

You don’t have to use GpiBitBlt with the bitmapped fonts, fortunately. In fact 
you can use the standard WinDrawText function we’ve used throughout this 
book with both bitmapped and vector fonts. 

The WinDrawText function is designed to make it easier to draw large 
amounts of text. It’s derived from the more primitive Gpi function 
GpiCharStringAt: 

General: LONG GpiCharStringAt(HPS hps, PPOINTL start, LONG count, 

PCH text) ; 

As Used: GpiCharStringAt(hps, &ptl , 20, "A Font of my Youth."); 

This function is pretty self-explanatory: Write the text (last parameter) start¬ 
ing at the POINTL indicated by the second parameter on the presentation 
space indicated by the first parameter. (The first parameter tells 
GpiCharStringAt how many characters are in the text string.) 

Note that there is no word wrap option, no centering option, nothing but you 
and the GPI. If the text string goes off the end of the presentation space, you 
are given no clue. 

If you want to find out how much space a particular GpiCharStringAt opera¬ 
tion is going to require, you use GpiQueryTextBox. 

General: BOOL GpiQueryTextBoxCHPS hps, LONG numchars, PCH text, 

LONG numpts, PPOINTL points); 

As Used: GpiQueryTextBoxChps, 20, "A Font of my Youth.", 
TXTB0X_C0UNT, query); 

The first four POINTLs returned by GpiQueryText indicate the corners of the 
box that the text would appear in if GpiCharStringAt were used to draw the 
text. (No text is actually drawn.) The last POINTL is the concatenation 
point—the place where you would start drawing the next string if you wanted 
to draw two strings from left to right. 

You can get the information using the following defines: TXTBOX_TOPLEFT, 
TXTBOX.BOTTOMLEFT, TXTBOX.TOPRIGHT, TXTBOX_BOTTOMRIGHT, and 
TXTBOX_CONCAT. This is also the order in which the data is returned, so 
you could use index 0 to get the top left, for example. 

You can define your array as having TXTBOX_COUNT elements and pass 
TXTBOX_COUNT as the fourth parameter to get all the data that GpiQuery¬ 
TextBox can provide, or you can specify a smaller number. (Note that the 
data is always returned in order, though, so you can’t retrieve only the bot- 
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tom-left and top-right coordinates, for example.) Usually it’s easiest just to 
use TXTBOX_COUNT and the defines to pick out the information you want. 

The information returned by GpiQueryTextBox presumes a bottom left of 
zero, so if you want the actual coordinates from any starting point, you need 
to adjust the points accordingly. 

The following code draws a character string at point ptl using the current 
font: 

GpiCharStringAt(hps, &ptl, 20, "A Font of my Youth."); 
GpiQueryTextBox(hps, 20, "A Font of my Youth.", 

TXTB0X_C0UNT, query); 

box[0] = query[TXTB0X_B0TT0MLEFT]; 
box[l] = query[TXTB0X_T0PLEFT]; 
box[2] - query[TXTBOX_TOPRIGHT]; 
box[3] = query[TXTB0X_B0TT0MRIGHT]; 
box[4] = box[0]; 

for (i=0;i<5;i-i+1) { 

box[i].x = box[i].x + ptl.x; 
box[i].y = box[i].y + ptl.y; 


GpiMove(hps, box); 

GpiPolyLine(hps, 4, box+1); 

Unforturnately, you can’t directly use the array returned from GpiQuery¬ 
TextBox in GpiPolyLine (the array goes from bottom left to top right, which 
would draw a diagonal line through the box), but the adjustments required 
are pretty minimal. 

The results from GpiQueryTextBox have a less obvious meaning when used 
with rotated text, as we’ll see later. 

We’ll come back to GpiCharString in a moment, but first we need to figure out 
exactly how to request and use a new font—a font different from the default. 


Highly Illogical Font Terminology 

To use a specific font when writing text, you need to do what is known as cre¬ 
ating a logical font. (Some might say that fonts are neither logical nor illogi¬ 
cal.) This is a logical font as opposed to an actual font; that is, creating an 
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actual font would require something like calling up the Font Editor and creat¬ 
ing a bitmap for A, then for B , and so on. 

But a system may have many fonts and, not surprisingly, they aren’t all 
loaded at once. Hence, you need to create a logical font, which is in essence a 
handle to an existing font and a notification to the GPI that you want to use a 
specific font. 

The call used to create a logical font is GpiCreateLogFont: 

General: LONG GpiCreateLogFont(HPS hps, PSTR8 name, LONG id, 

PFATTRS fat) 

As Used: GpiCreateLogFont(hps, NULL, 1, &fat); 

You can ignore the PSTR8 parameter (a PSTR8 is an eight-character string). 
The ID returned in the third parameter is the handle by which you will refer 
to the logical font. 

The last parameter is the most complex thing about the call, and fortunately, 
you can mostly ignore it too! The FATTRS structure contains a number of 
fields, most of which you’ll never care about. The fields that you will care 
about are: 

v* usRecordLength, which you will usually set to be the size of FATTRS 

v* fsSelection, which allows you to request the following special effects: 
FATTR_SEL_ITALICS, FATTR_SEL_BOLD, FATTR_SEL_UNDERSCORE, 
FATTR_SEL_STRIKEOUT, and FATTR_SEL_OUTLINE 

v* IMaxBaselineExt, which you use to request a font height 

/>* lAveCharWidth, which you use to request a font width 

v* szFacename, which you use to request a particular typeface, such as 
Swiss or Times Roman 

v* fsFontUse, which you use to tell GpiCreateLogFont how you are going to 
use the font, with any combination of FATTR_FONTUSE_NOMIX (you’re 
drawing text only, with no graphics integration), FATTR_FONTUSE_OUT- 
LINE (you want an outline font), and FATTR_FONTUSE_TFlANS- 
1 FORMABLE (you’re going to be doing special effects with the font) 

GpiCreateLogFont returns either FONT_MATCH (a font matching your 
request was found), FONT_DEFAULT (no match was found, and a default font 
is being used), or GPIJERROR (you passed a bad HPS, for example). 
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Creating and using a logical font 

You can create and use both raster fonts and vector fonts with GpiCreateLog- 
Font, though there are some subtle (and important) differences to keep in 
mind. 


In particular, when you request a bitmap font, you have to get everything 
exactly right. For example, if you ask for a Courier font that is 13-by-7 and 
there is only a 13-by-8 and a 13-by-6 bitmap font available, you get 
FONT_DEFAULT—that is, the font ID returned by GpiCreateLogFont indicates 
the default font. 



You can use OS/2 EPM.EXE (the Enhanced Editor) to determine what fonts 
are available on your system. Select Preferences from the Options pull-down 
menu, and select the fonts page of the settings notebook. 

This can make it much easier to get the bitmap font settings right. 


Here’s an example of how to load and create a bitmap font. This example 
requests a 12-by-12 bitmapped Courier font and then displays a text string in 
the resultant font (whether the attempt to create the font was successful or 
GpiCreateLogFont returned FONT_DEFAULT). 


memset(&fat, 0, sizeof(FATTRS)); 


/* raster font */ 

fat.usRecordLength = sizeof(FATTRS); 
fat.1MaxBaselineExt = 12; 
fat.1AveCharWidth = 12; 
strcpy(fat.szFacename, "Courier"); 
fat.fsFontUse = FATTR_FONTUSE_NOMIX; 


GpiCreateLogFont(hps , NULL, 1, &fat); 

GpiSetCharSet(hps , 1); 

GpiQueryFontMetrics(hps , sizeof fm, &fm); 



ptl.x = rcl.xLeft; 

ptl.y = rcl.yTop - fm.1MaxAscender; 

GpiCharStringAt(hps, &ptl , 20, "A Font of my Youth."); 

GpiQueryTextBox(hps, 20, "A Font of my Youth.", 

TXTB0X_C0UNT, query); 

One indication that a raster font is being requested is the specification of the 
height (IMaxBaselineExt) and width (lAveCharWidth) of the font. Those 
would be set to 0 if a vector font was being requested. 
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As this example shows, you only need call GpiSetCharSet with the logical font 
ID (in this case, 1) to cause all subsequent text output to come out in that 
font. 

WinDrawText, for example, is affected by this call, and you needn’t use 
GpiCharStringAt just because you requested a nondefault font, m 



Here again (as in Chapter 4) I used GpiQueryFontMetrics to obtain valuable 
information about the dimensions of the font currently in use. Always remem¬ 
ber that just because you requested a particular font from GpiCreateLogFont, 
doesn’t mean you got it. (You can’t always get what you want.) 


At the end of this chapter there is a section on the most useful fields of the 
FONTMETRICS structure. 


By contrast, selecting a vector font is somewhat easier, if only because you 
don’t specify height and width, and GpiCreateLogFont will return near misses 
if it can find something close to the requested attributes: 

/* outline font */ 

GpiDeleteSetlcKhps, 1); /^Delete previous raster font */ 

fat.fsSelection = 0; /*FATTR_SEL_OUTLINE;*/ 

fat.1MaxBaselineExt = 0; 

fat.1AveCharWidth = 0; 

strcpy(fat.szFacename , "Courier"); 

fat. fsFontllse = FATTR_FONTUSE_NOMIX | FATTR_FONTUSE_OUTLINE | 
FATTR_FONTUSE_TRANSFORMABLE; 

GpiCreateLogFont(hps, NULL, 1, &fat); 

GpiSetCharSet(hps, 1); 



The key to getting a vector font is to set IMaxBaselineExt and lAveCharWidth 
to 0, and to set the FATTR_FONTUSE_OUTLINE and FATTR_FONTUSE_TRANS- 
FORMABLE fields. (Outline and transformable fonts are always vector fonts.) m 

You could use the font retrieved by this call in exactly the same way as the 
previously requested bitmap font, but since we’ve gone through the trouble 
of requesting a vector font, we might as well take a look at how to use it. 


Special Text Effects 

One of the reasons vector fonts take so long to draw is that they don’t pre¬ 
sume a size. An / isn’t drawn as a single vertical line, for example. Each “line” 
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of a vector font is usually at least two lines. To make the font bigger, the 
lines are drawn farther and farther apart, and the area in between the lines 
is filled in. 



Because of this characteristic, it is possible to use vector fonts to draw text 
messages where the letters aren’t filled in with solid black, but contain some 
other pattern, such as vertical or horizontal lines. 

Also because of this, vector fonts are sometimes called outline fonts. 


To get a taste for the potential power of vector fonts, we’re going to look at 
three Gpi calls that make scaling and rotation possible: GpiSetCharMode, 
GpiSetCharAngle, and GpiSetCharBox. 


General: BOOL GpiSetCharBox(HPS hps, PSIZEF size); 

As Used: GpiSetCharBox(hps, &fs); 

The purpose of GpiSetCharBox is to set the size of the character box—the 
height and width occupied by a character. 

GpiSetCharBox uses the interesting FIXED data type, which is, in fact, nothing 
but a LONG—a LONG that’s interpreted as two SHORTS, where the first short 
indicates the integer part of the number, and the second indicates the frac¬ 
tional part. 

The fractional part has 65,536 as a denominator. So to get a fraction of 1/16, 
you would set the second short to 4096. To get approximately 1/10, you 
would set the second short to 6554 (rounding up). 

The MAKEFIXED macro, shown in the following code snippet, turns two 
shorts into the fixed type. (This makes a very large font when used with 
GpiSetCharBox.) 


fs.cx = MAKE FIXED(75 , 0); 
fs.cy = MAKEFIXED(75 , 0); 



General: BOOL GpiSetCharAngle(HPS hps, PGRADIENTL target) 

As Used: GpiSetCharAngle(hps, &pt12); 

The GRADIENTL structure is identical to the POINTL structure—two LONG 
fields called x and y. You can use POINTL and GRADIENTL interchangeably. 

Despite its name, GpiSetCharAngle really doesn’t set the character angle. 
Instead it sets the “destination” for a string of text. Imagine you are drawing a 
line of text starting at (0,0). If the line is being drawn horizontally from left to 
right, you expect the last character to be drawn at (n, 0), where n represents 
a positive integer describing how far to the right the text would extend. 
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What GpiSetCharAngle lets you do is tell PM where you want the text to end 
up, or, more accurately, a point that you would like the text to pass through. 
If the text is too short to pass through the point, this function does not cause 
the text to be stretched out. 

Normally, of course, text is drawn from left to right and from top to bottom. 
But if the GRADIENTL’s x field is negative, the text will be drawn from right to 
left, and if the GRADIENTL’s y field is negative, the text will be drawn from 
bottom to top. 

The impact of this varies depending on the current character drawing mode. 

General: BOOL GpiSetCharMode(HPS hps, LONG mode); 

As Used: GpiSetCharMode(hps, CM_M0DE3); 

If CM_MODEl is selected, the text will be drawn in the usual manner, ignoring 
scaling and rotation. If CM_MODE2 is selected, the text will be drawn on a 
diagonal, but not scaled or rotated. In other words, like this: 

A 

w 

o 

r 

d 


If CL_MODE3 is specified, the characters themselves will rotate along with 
the text. 



You can do the following experiment to figure out how GpiSetCharAngle 
works in conjunction with CL_MODE3: Write ROTATE on a piece of scrap 
paper, then jam a pencil through the paper at the lower left corner of the let¬ 
ter R. (You can use a record player spindle for this experiment, if you remem¬ 
ber what a record player is and you still have one.) Figure 19-1 illustrates this 
experiment. 


If you twirl the paper around this axis, the characters rotate along with the 
text, simulating exactly what happens with GpiSetCharAngle and CL_MODE3. 
If you rotate the text so it is now going from right to left, you’ll notice that all 
the characters are upside down and backwards. (Figure 19-2 in the next sec¬ 
tion shows text that hasn’t been rotated quite that far. 

If you can figure out what the coordinates of the bottom left side of the last 
letter in the text should be (the E in this case), you can use GpiSetCharAngle 
to create any effect you want. 
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Figure 19-1: 
Text 
rotation at 
33 rpm. 




This experiment can also keep you from falling into a trap when using 
GpiSetCharAngle and GpiQueryTextBox: Rotate the text so to that it is in its 
normal left-to-right orientation. The bottom left-hand corner is where the axis 
is, and the top right-hand corner is diagonally across the paper from it—the 
outer tip of the top “fork” of the E. Similarly, the bottom right corner is the 
outer tip of the bottom “fork” of the E and the top left is the point at the top 
left edge of the R. 

Well, from GpiQueryTextBox’s standpoint, these corners never change, no 
matter how you rotate the text. That’s important to remember. If you rotate 
the text all the way around, the tips of the forks don’t suddenly become the 
top left and bottom left points of the text (from GpiQueryTextBox’s stand¬ 
point, that is). 

It’s easiest to think of it this way: The axis is always the bottom left and all 
the other points have fixed relations to it, based on an unrotated orienta¬ 
tion. 
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A font from igonth 

In my youth, before computers became a household word, I used to type out 
things on devices called typewriters. The great historian, Will Durant, 
reminded us that progress is just a theory. And a case in point is that no mat¬ 
ter what, a typewriter never “lost” a manuscript (unlike today’s modern word 
processors). 

Anyway, I worked on manual and electric typewriters as a young child, and 
most of them used a Courier-like font, which explains the name of this pro¬ 
gram and its output. (I am still fond of Courier, which brings back memories 
of white-out and wadded up paper...) The sample program given here creates 
the output shown in Figure 19-2, which neatly sums up what we’ve covered in 
this chapter. 



You can use the code to test various font rotations and scalings, and to get a 
better sense of how these effects actually work. 

//define INCL_GPI 
//define INCL_WIN 
//include <os2.h> 

//include <stri ng. h> 


//include "font.h" 
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MRESULT EXPENTRY ClientWndProc(HWND, ULONG, MPARAM , MPARAM); 

#define APPNORMAL 0 
//define INITFAILURE -1 
//define USERQUIT -2 

int main (void) 


HAB 

hab; 


/* 

anchor block handle 

*/ 

HMQ 

hmq; 


/* 

message queue handle 

*/ 

HWND 

hwndFrame, hwndClient; 

/* 

handles to windows 

*/ 

QMSG 

qmsg; 


/* 

message 

*/ 

char 

szClassName[] = 

"Fonts" 




char 

szWindowTitle[] 

= "Testing 

Cl 

CD 

1— 

O 

Ll_ 



ULONG f1FrameOpts = FCF_STANDARD; 

ULONG appState = APPNORMAL; 

hab = Win Initialize(0); 

hmq = WinCreateMsgQueue(hab, 0); 

if (!WinRegisterClass(hab, szClassName, ClientWndProc, 

CS_SIZEREDRAW, 0)) 
appState = INITFAILURE; 

hwndFrame = WinCreateStdWindow(HWND_DESKTOP, WS_VISIBLE, 

&flFrameOpts, szClassName, 
szWindowTitle, 0L, 0, 
FONTPROGRAMID, 

&hwndClient); 

if ((appState==INITFAILURE) || (hab==NULLHANDLE) || 

(hmq==NULLHANDLE) || (hwndFrame==NULLHANDLE)) 

WinMessageBox(HWND_DESKTOP, HWND_DESKTOP, 

"Unable to initialize application.", "ERROR!", 

0, MB_CANCEL | MB^ERROR); 

el se 

while (appState==APPNORMAL) { 

while (WinGetMsgChab, &qmsg, 0, 0, 0)) 

WinDispatchMsg(hab, &qmsg); 

if (WinSendMsg(hwndClient, WM_COMMAND, 

MPFROM2SHORT(CMD_VERIFY, 0), 0) != MBID_CANCEL) 
appState = USERQUIT; 

if (qmsg.hwnd == NULLHANDLE) /^system shutdown */ 

if (appState != USERQUIT) WinCancelShutdown(hmq, FALSE); 
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WinDestroyWindow(hwndFrame); 
WinDestroyMsgQu6ue(hmq); 

WinTerminate(hab); 

return 0; 

} 


MRESULT EXPENTRY ClientWndProc(HWND hwnd, ULONG msg, MPARAM mpl, 
MPARAM mp2) 


HPS 

RECTL 

ULONG 

POINTL 

FATTRS 

FONTMETRICS 

SIZEF 

i nt 


hps; 
rcl ; 
cmd; 

ptl, ptl 2, query[TXTB0X_C0UNT], box[5]; 
fat; 
fm; 
fs; 
i ; 


/*event handler*/ 
switch(msg) { 

case WM_PAINT: 

hps = WinBeginPaint(hwnd, NULLHANDLE, NULLHANDLE); 

WinQueryWindowRect(hwnd, &rcl); 

WinFi11Rect(hps, &rcl , CLR_WHITE); 

memset(&fat, 0, sizeof(FATTRS)); 

/* raster font */ 

fat.usRecordLength = sizeof(FATTRS); 
fat.1MaxBaselineExt = 12; 
fat. 1AveCharWidth = 12; 
strcpy(fat.szFacename, "Courier"); 
fat.fsFontUse = FATTR_FONTUSE_NOMIX; 

GpiCreateLogFont(hps, NULL, 1, &fat); 

GpiSetCharSetChps, 1); 

GpiQueryFontMetrics(hps, sizeof fm, &fm); 

ptl.x = rcl.xLeft; 

Ptl.y = rcl.yTop - fm.1MaxAscender; 

GpiCharStringAt(hps, &ptl, 20, "A Font of my Youth."); 
GpiQueryTextBox(hps, 20, "A Font of my Youth.", 
TXTB0X_C0UNT, query); 
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box[0] = query[TXTB0X_B0TT0MLEFT]; 
box[l] = query[TXTB0X_T0PLEFT]; 
box[2] = query[TXTBOX_TOPRIGHT]; 
box[3] = query[TXTB0X_B0TT0MRIGHT]; 
box[4] = box[0]; 

for (i=0;i<5;i=1+1) { 

box[i].x = box[i].x + ptl.x; 
box[i].y = box[i].y + ptl.y; 

} 


GpiMove(hps, box); 

GpiPolyLine(hps, 4, box+1); 

/* outline font */ 

GpiDeleteSetlcK hps , 1); 

fat.fsSelection = 0; /*FATTR_SEL_OUTLINE;*/ 

fat.1MaxBaselineExt = 0; 

fat.1AveCharWidth = 0; 

strcpy(fat.szFacename ,"Courier"); 

fat.fsFontUse = FATTR_FONTUSE_NOMIX | FATTR_F0NTUSE_0L1TLINE | 
FATTR_FONTUSE_TRANSFORMABLE; 

GpiCreateLogFontChps, NULL, 1, &fat); 

GpiSetCharSet(hps, 1); 

GpiSetCharModeChps, CM_M0DE3); 
ptl.x = rcl.xRight; ptl.y = rcl.yTop; 
ptl2.x = -rcl.xRight; 
ptl2.y = -rcl.yTop; 

GpiSetCharAngle(hps, &pt!2); 
fs.cx = MAKEFIXEDC75, 0); 
fs.cy = MAKEFIXEDC75, 0); 

GpiSetCharBoxChps, &fs); 

Gpi Char St ri ngAt (hps , &ptl , 20, ''A Font of my Youth.''); 

WinEndPaint(hps); 
return 0; 


case WM_COMMAND: 

switch(SH0RT1FROMMPCmpl)) { 
case CMD_VERIFY: 
cmd = MB ID_N0; 

/* if (data_modified) */ { 

cmd = WinMessageBoxCHWND_DESKTOP, hwnd, 
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"Do you want to save your work before exiting?", 

"Query", 0, MB_YESNOCANCEL | MB_QUERY); 

/* if cmd==MB_YES save_data */ 

} 

return (MRESULT)cmd; 

./* case CMD_OTHERCOMMANDS: */ 

} /* end WM_COMMAND messages */ 

} /*end event handlers */ 
return WinDefWindowProc(hwnd, msg, mpl, mp2); 


FONT.H is copied from BASIC2.H, as usual: 


# define 

FONTPROGRAMID 

1000 

//define 

CMD_HELP 

1001 

//define 

CMD_VERIFY 

1002 

//def i ne 

MID_FILE 

2000 

//define 

CMD_FILEOPEN 

2001 


Font Metrics 

As promised, this chapter ends with an enumeration of font fields that you 
are likely to find useful in your programs. Figure 19-3 labels some of these to 
make them easier to understand. 




282 Part IV Polish and Panache__ 

szFamilyName and szFaceName—The first describes the family that the 
font belongs to (for example, System or Swiss or Times New Roman), 
and the second describes the family and the effects that apply, as in 
Swiss Bold or Times New Roman Bold Italic. 

y* usCodePage—Contains the current code page, which you only need to 
concern yourself with if you are writing applications that will be used in 
multiple languages. 

) u* lEmHeight—The height of a capital M in the specified font, measured 
from the baseline. This is the font’s point size. 

y* lExHeight—The height of a lowercase x in the specified font, measured 
from the baseline. This is the preferred height of lowercase letters. 

I v* IMaxAscender—The distance from the baseline to the top of the cell. 

u* IMaxDescender—The distance from the baseline to the bottom of the 
cell. 

V lLowerCaseAscent—The maximum distance above the baseline for an 
unaccented lowercase character. 

y* lLowerCaseDescent—The maximum distance below the baseline for an 
unaccented lowercase character. 

u* llnternalLeading—The distance from the top of a capital letter to the top 
of the cell. 

y» lExternalLeading—The distance from the top of the cell to the bottom of 
the cell in the row above. (Obviously, this is a request to the font users, 
since the font designer can’t enforce this within the cell definition itself.) 

v* lAveCharWidth—The average width of a character. 

I J y* lMaxCharlnc—The maximum width of a character cell. 
y» lEmlnc—The width of the capital letter M in the specified font. 
yx IMaxBaselineExt—The cell height. 


Conclusion 

It probably won’t surprise you that we’ve barely scratched the surface of the 
text and font possibilities of PM. But even more than graphics, fonts are the 
domain of a very small group of people. 

And so, with a heavy heart, we leave this topic to go on to something more 
general. 
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Dynamic Link Libraries 


!m This Chapter 

What are dynamic link libraries (DLLs) 

Creating function DLLs 

DLL basics 

Resource DLLs 

DLLs on request 

Module definition files 


/ magine, if you will, that it is the mid-to-late 1980s. A bizarre period of 
American affluence is coming to an end. Reagan is a lame-duck president. 
The Democrats “can’t lose” the next presidential election. And computer 
hard drives are getting bigger and bigger—but still aren’t big enough to keep 
up with increasingly bigger and bigger software packages. 

Large software becomes an issue: People look at the half-dozen or so major 
applications they use from day to day—almost always the biggest applica¬ 
tions on their disk—and noticed that each one has its own way of doing 
things, and its own code for doing it. 

Pretty much all applications put up some kind of window—some display text 
only, some graphics—but they all contain large amounts of code that does 
essentially the same things! Why can’t these programs share common code to 
do what we need to do, people wonder? Not only can we save disk space, 
goes the reasoning, but each application will look and feel alike because each 
will use the same basic function calls to get things done. 

And so, the Dynamic Link Library was born—and You Are There! 

Of course, programs are bigger than ever today, and now we have innumer¬ 
able .DLL files cluttering up our disks that we don’t even know about and 
can’t even tell if they’re safe to delete. And a change to a DLL can cause pro- 
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grams that use the DLL to crash, so we often need to keep different versions 
of the same DLL around—but things are better now! Really! 

Progress is a theory. 


The Concept of Dynamic Linking 

In truth, although DLLs do create problems and probably weren’t very well 
designed from the get-go, all of the programs in this book—indeed, OS/2 pro¬ 
gramming itself—would be problematic, if not impossible, without them. 


The entire PM API, as well as OS/2’s considerable collection of non-graphical 
functions, is implemented through DLLs. The Workplace Shell derives all of 
its functionality from the various system DLLs. 


None of which actually explains what a DLL is, of course, or why it’s called 
dynamic linking. 

To understand what dynamic linking is, it helps to look at static linking. Static 
linking was the norm for DOS programmers. If you required some service in 
your program, you bought a library and either compiled the source with the 
source of your program or linked the object code into your program s object 
code to create a single executable. 


This is called static linking because the functions are all there, physically a 
part of your executable. The function code and your code are bonded 
together at compile time, and are bonded forever. If any part of the program 
changes, whether it is your source code or the included libraries, then you 
must recompile or relink the entire program. 

By contrast, in dynamic linking the program requests certain services of the 
library, and has to know where the library is only when the program is com¬ 
piled. The library code and the program code are physically separate, and 
the library code can be loaded into memory by the operating system when 
the program is running— and only if the program actually requests one of the 
library’s services! 

So the theoretical advantages of DLLs include things such as smaller executa¬ 
bles, less space taken up overall by executables because they share common 
code, potentially faster loading time (because the programs are smaller), and 
independent upgrading of modules. 
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Module is a generic term encompassing both programs and DLLs. 

This last issue is particularly important: Because the program and the library 
are physically separate, the program can be changed and recompiled without 
the library having to be changed or recompiled. Similarly, the library can be 
changed without breaking the programs that use it. (Later on in this chapter 
and in Chapter 23, we’ll see how this can work. 

Code that uses code from another library is called a client. All of our PM pro¬ 
grams are clients of the PMWIN.DLL, where the Win* API is stored. 

All of these theoretical advantages are more or less realized in practice, 
although the advantages of having less space taken up by code is offset by 
having multiple copies of DLLs and unused DLLs remaining on disks because 
users don’t know when to delete them. Also the loading speed advantage can 
be offset by the fact that the time overhead of calling dynamically linked 
functions is greater than that of calling statically linked functions. Programs 
may run slower, therefore, even if they load faster. 

There are some other disadvantages, too, in using DLLs. In particular, a 
change to a DLL can break a wide variety of programs. In theory, a well- 
designed DLL and well-behaved clients should be immune to changes made 
to each other, but in practice—well, each new upgrade of OS/2 is guaranteed 
to cause problems in existing applications, and those problems can’t always 
be blamed on badly behaved apps. 


Creating a BLL 

At a minimum, a DLL requires two source files to be created. The first is a file 
containing code (a .C or .PAS file, for example). The code contains no main 
function or program block, for a .DLL is never meant to be run. Instead, the 
code comprises one or more functions that can be provided to clients or that 
provide services useful to other functions, but that are hidden from clients. 

The file that determines which of the functions in the source file will be avail¬ 
able to clients is called the module definition file , and is usually given the 
same name as the source file, but with an extension of .DEF. (We’ll examine 
the .DEF file a little more closely in the next section.) 

In addition, the .DLL is often accompanied by a header file (.H) containing 
prototypes of the library’s functions as well as any data types that might be 
useful to clients. This isn’t strictly necessary, but it is polite. 
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The implementer of a .DLL may have an implementation header file (.IH), 
which describes functions and data types that aren’t going to be made avail¬ 
able to the client. 

Also, a .DLL can contain resources, just as a program can, so the .DLL might 
have one or more .RC files associated with it, as well as .ICO, .BMP, and .PTR 
files. 

In fact, as we’ll see at the end of this chapter, a DLL can contain only 
resources, with no functions at all, if such a resource library is desired. 

You’ll usually have to “tell” your programming IDE that the project you’re 
working on is a .DLL. If you’re using the command line, there will be special 
options to accommodate a .DLL. 

For example, with the IBM compiler, you must specify the /Ge- option, so that 
the linker doesn’t include the executable run-time library in the compiled 
.DLL. Also, you must give the compiler the name of the .DEF file so it can gen¬ 
erate a .DLL properly. 


A sample simple Thing library. 

A DLL can be a series of unrelated functions, logically related functions (like a 
bunch of graphics routines), or actually related functions, such as the PM 
API, where you request a window handle to start and then use that handle 
over and over again to request services. 

I’ve created a simple library to illustrate how you might code a DLL using 
that last approach to handle “things.” Here’s SUBDLL.H, which gives the defi¬ 
nition of “things”: 

typedef struct { 

LONG accesses; 

CHAR name[ll]; 

) THINGDATA; 

typedef THINGDATA *PTHINGDATA; 

PTHINGDATA API ENTRY thingCreateThing() ; 

PCHAR API ENTRY thingAccessThing(PTH INGDATA); 

LONG APIENTRY thingQueryAccesses(PTHINGDATA); 

VOID APIENTRY thingDestroyThing(PTH INGDATA); 
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Throughout this book we’ve been using EXPENTRY, which is the necessary 
directive for window procedures. DLL functions, on the other hand, must be 
defined using APIENTRY, as shown here. 



A DLL can have an EXPENTRY function, so it is possible to have a DLL that 
contains a window class. This is obvious from the fact that all of the windows 
(of any type) we’ve created up to this point have been contained in DLLs. 

However, the EXPENTRY function can’t be part of the DLL’s interface. That’s 
all right, because we don’t generally call window procedures directly. 


As you’ll see, I have chosen to give the client complete access to SUBDLL’s 
capabilities. I have not hidden any functions or data types. Hiding these capa¬ 
bilities, however, would be as easy as leaving the function or structure defini¬ 
tion out of the header file. (They would appear instead in the DLL’s source 
code file, or in a separate implementation header file, as discussed in the last 
section.) 


Here’s SUBDLL.C, containing the source code for the DLL: 


//include <os2.h> 

//i ncl ude "subdl 1 . h" 


ULONG _System _DLL_InitTerm(ULONG hmodule, ULONG flag) 

{ 

switch(flag) { 

case 0: /* The DLL is being Initialized */ 
return 1; 

case 1: /* The DLL is being unloaded */ 
return 1; 

} 

return 0; /* A zero return is an error */ 

} 

PTH INGDATA APIENTRY thingCreateThing() 

{ 

PTHINGDATA thing; 

thing = (PTHINGDATA) ma 11 oc(sizeof (THINGDATA)); 
if (thing != NULL) { 
thing->accesses = 0; 
strcpy(thing->name, "Thing"); 

} 


return thing; 
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PCHAR API ENTRY thingAccessThing(PTH INGDATA thing) 
{ 

if (thing==NULL) 
return NULL; 
el se { 

thing->accesses = thing->accesses + 1; 
return thing->name; 

} 


LONG API ENTRY thingQueryAccesses(PTH INGDATA thing) 
{ 

if (thing==NULL) 
return -1; 

else return thing->accesses ; 

} /* endif */ 


VOID API ENTRY thingDestroyThing(PTH INGDATA thing) 
{ 

free(thing); 

1 


The code here is pretty simple, and not the point of our studies, anyway. 

Note that in this case, I have chosen to give a pointer to the structure back to 
the client when it creates a thing, and the client must use the thing pointer to 
access the rest of the API functions. 

To hide the information from the client, I could have supplied a “fake” defini¬ 
tion for PTHINGDATA, perhaps making it an equivalent of a PVOID. 

Another possibility, interesting in its own right, would have been for me to 
create a linked list of things created by thingCreateThing. DLLs can have 
global data, so I could have done something like this (in SUBDLL.C): 

typedef struct { 

LONG accesses; 

CHAR name[ll]; 

LONG handle; 

THINGDATA *next; 

} THINGDATA; 

typedef THINGDATA ^PTHINGDATA; 


PTHINGDATA thinglist; 
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Then, I could have returned a handle to a thing from thingCreateThing, which 
the client would have to use to request the other SUBDLL services. We could 
speculate that PMWIN.DLL (containing the PM API) works in a similar fashion. 


Starting, up amt Winding down 

Observe that one of the DLL functions does not use APIENTRY, but instead 
uses _System, and a lot of underscores: _DLLJnitTerm. 


_DLL_InitTerm is usually called when the DLL is first loaded and when the 
DLL is removed from memory. (You can specify exactly when you want it 
called, as we’ll see in the next section.) 

_DLL_InitTerm is called with the handle to the module that OS/2 is going to 
assign. (In other words, this is the handle that the client program is going to 
use to refer to the module, as we’ll see when we use SUBDLL.) The flag passed 
is either 0, if the DLL is being initialized, or 1, if the DLL is being terminated. 

The client receives the return from JDLLJnitTerm. A zero means that an 
error occurred. Any nonzero value indicates success. 



Even though SUBDLL doesn’t do anything in JDLLJnitTerm, I’ve included it 
here for future reference, and because it’s easy to forget its existence. 

If you maintain a list of objects created by your DLL, you might initialize the 
list in _DLL_InitTerm. 


The module definition file 

Throughout this book, I’ve tried to keep the projects as simple as possible. 
Our first programs were only source files. Later on we added resource files 
and header files (to identify the resources). 

One file I’ve left out completely (until now) is the module definition file (.DEF). 
I could do this because most compilers nowadays (and all the IDEs) allow 
you to specify the target of a project. (That is, is the target a command line 
OS/2 program, or a windowed OS/2 program, or something else?) 

However, it used to be a requirement for a program to have its own .DEF file, 
which usually looked something like this: 


NAME PROGNAME WINDOWAPI 

DESCRIPTION ’Copyright (C) 1999 - Version 1.1' 
PR0TM0DE 
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The first word on the line is an option that the linker uses to turn the .OBJ file 
into its final form. 


For example, the NAME option gives the application’s name and is followed 
by the type of application: WINDOWAPI (a PM application), WINDOWCOM- 
PAT (a text mode app able to run in a window on the Desktop), or NOTWIN- 
DOWCOMPAT (a text mode app that must be run in a full-screen OS/2 
command line session). 



It may not have occurred to you, but you can write a program that requires 
the user to start it from a full-screen OS/2 session. 

Previously I said that the application has to be text mode, but if you were so 
inclined, you could write a very DOS-like program that used non-Presentation 
Manager graphics. 


The text following DESCRIPTION gets embedded into the final file, and so is 
used for copyright or version control information. 


PROTMODE is usually specified for OS/2 applications, and indicates that the 
program runs in protected mode, not real mode. 

Generating a DLL requires a .DEF file, so we can no longer ignore this type of 
file. A DLL .DEF file uses a few different options than a program’s .DEF file. 
Here’s the .DEF for SUBDLL: 


LIBRARY SUBDLL 

EXPORTS thingCreateThing 

thingAccessThing 
thingQueryAccesses 
thingDestroyThing 

Now, this is a pretty minimal .DEF file because I’ve left just about everything 
to the defaults. A DLL’s .DEF file begins with the word LIBRARY, followed by 
the name of the DLL (which is usually the name of the source code file minus 
its extension). 



The name of the DLL may be followed with either INITGLOBAL or INITIN- 
STANCE, and TERMGLOBAL or TERMINSTANCE. Using INITGLOBAL indicates 
that JDLLJnitTerm will be called (with a 0 flag) for the DLL the first time the 
DLL is loaded, whereas using INITINSTANCE indicates that the function will 
be called for every client program. 


TERMGLOBAL and TERMINSTANCE similarly control the calling of _DLL_Init- 
Term (with a 1 flag). 
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The second crucial element of the DLL’s .DEF file is the EXPORTS statement, 
which lists all of the functions that will be accessible to clients of the DLL. 

Another especially useful option of the .DEF file is DATA. For either a pro¬ 
gram or a DLL you can specify MULTIPLE (default for programs) or SINGLE 
(default for DLLs). 

SINGLE indicates that no matter how many times the module is run or the 
DLL is loaded, there will be only one data space shared by all the instances. 

MULTIPLE indicates that each instance of the module will have its own data 
separate from any other instances. 


Using a DLL 

Let’s look at a program that uses the Thing DLL. (This is not a PM program.) 

^include <os2.h> 

#include "subdl1.h" 


int main (void) 

{ 

PTHINGDATA thing; 

thing = thingCreateThing(); 
printfCthingAccessThing(thing)); 
printf(thingAccessThing(thing)); 

printf("%d accesses of thing\n", thingQueryAccesses(thing)); 
thi ngDestroyThing(thing) ; 
return 0; 


Doesn’t look any different from any other program, does it? I mean, except 
for the inclusion of the SUBDLL header file. 

Well, think about it: Why should it be any different? We’ve been using DLLs 
from the get-go; why should one of ours be any different from OS/2’s? 

The only difference comes when you compile the program. The compiler and 
linker flag the thing calls as unresolved references. So how do we let the com¬ 
piler know that we’re referring to a particular .DLL? 
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The answer, unfortunately, is: It depends. Your IDE should have an option 
switch that allows you to specify not only which DLLs you want to include 
but also where to look for DLLs. 

Your CONLIG.SYS contains a LIBPATH= statement that contains a list of direc¬ 
tories that OS/2 will search in the process of looking for DLLs. 

But even if you’ve specified what DLLs you want to use, the linker needs to 
have some way of determining which functions from the DLL you’re going to 
import. 

In the old days of OS/2 programming, this was done in the client’s .DEL file 
with an IMPORTS statement. An IMPORTS statement for the USEDLL.C pro¬ 
gram above would look something like: 

IMPORTS subdll.thingCreateThing 

subdll.thingAccessThing 
subdll.thingQueryAccess 
subdll.thingDestroyThing 

Now, if you’re thinking, you realize that we’ve been using DLLs all along with¬ 
out a single .DEL file, and (ergo) without a single IMPORTS statement. 

The OS/2 Warp Toolkit comes with a special program called IMPLIB.EXE, 
which turns a .DEL file into a .LIB file. A .LIB file compiled as part of a pro¬ 
gram provides the linker with all the necessary information about what func¬ 
tions can be imported from a DLL and where the .DLL can be found! 

IMPLIB.EXE is called by specifying the .LIB filename followed by a list of .DEL 
or .DLL files whose functions will ultimately make up the library: 

implib subdll.lib subdll.def 

Prom this you may infer correctly that a .LIB file may provide information 
about more than one DLL. As a matter of fact, the majority of OS/2’s API 
(from all of its DLLs) is contained in a single .LIB file called OS2386.LIB. 

You can test out SUBDLL.DLL from the command line by compiling USEDLL.C 
like so: 

icc usedl1.c subdll .lib 

This should be approximately the same format used by any C++ compiler. 

The output from USEDLL.EXE is less than spectacular: 

ThingThing2 accesses of thing 
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In fact, it’s somewhat distasteful. The least we could do is put a newline after 
each Thing. 

Let’s do that now. But instead of making the change to USEDLL, let’s make 
the change to SUBDLL. Change the thingCreateThing function to the follow¬ 
ing, adding the \n newline character to the name: 

PTHINGDATA APIENTRY thingCreateThing() 

{ 

PTHINGDATA thing; 

thing = (PTHINGDATA) mal1oc(sizeof (THINGDATA)); 
if (thing != NULL) { 
thing->accesses = 0; 
strcpy(thing->name, "Thing\n"); 

} 

return thing; 

} 

Now recompile SUBDLL only. 

Now, without recompiling , run USEDLL.EXE. 

Thing 

Thing 

2 accesses of thing 

You see? The output changes even though the program itself has not been 
recompiled. This is one of the major advantages of DLLs. (Usually put to 
more useful purposes than this, of course!) 


The Resource Library 

A dynamic link library can be used to store more than functions. Like a pro¬ 
gram, it can also be used to store resources. Anything that you might define 
in a program’s .RC file can be defined in a DLL’s .RC file and accessed by 
clients of the DLL. 

Not only that, a DLL can contain zero functions, and be used only as a sup¬ 
plier of resources. Let’s take a look at how that might work. 

For our example, we’ll create a small library that contains two pointers. We 
can then modify the POINTER program from Chapter 8 to try out the 
resource DLL. Use the GRAB.PTR from that chapter and create another 
pointer for this experiment. (I loaded the TESTICO.ICO file into the icon edi¬ 
tor and copied it to the clipboard, then I created a new pointer file in the icon 
editor, and pasted the TESTICO image into it.) 
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It doesn’t really matter what you do, though. You just need to create a 
resource file that defines two pointers. Here’s my PTRLIB.RC: 

POINTER 1 GRAB.PTR 

POINTER 2 TARGET.PTR 

1 could have had a PTRLIB.H file here that defined GRAB and TARGET as 1 
and 2, respectively. 

Now we need a .C file. You can’t have a DLL without a code file. Here it is: 

/* Dummy C file for resource DLLs */ 

That one line is the whole thing. Prom this, your C compiler can create a 
.DLL. The .DLL will have no functions in it, but that’s the point of this experi¬ 
ment. 

Now you need to compile the resource file. We’ve normally left that up to the 
IDE we’ve been working in, but it’s pretty straightforward to do it from the 
command line: 


rc -r ptrlib.rc 



Your resource compiler may have a different name than RC.EXE, which is the 
IBM Toolkit-supplied compiler. 

The -r option tells the resource compiler to create a binary .RES file from the 
text .RC file. We can link this .RES file into the .DLL: 


rc ptrlib.res ptrlib.dll 

That’s all it takes. RC does the rest. 


Dynamically Loading a Resource File 

You can now go back to the safety and comfort of your preferred IDE and 
modify the pointer program. Here is the entire program, with the modifica¬ 
tions. In particular, observe the WM_CREATE and WMJDESTROY handlers. 

//define INCL_GPI 
//define INCL_WIN 
//define INCL_D0S 
//i ncl tide <os2.h> 

//include <string.h> 
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MRESULT EXPENTRY ClientWndProc(HWND , ULONG, MPARAM, MPARAM); 

int main (void) 

{ 

HAB hab; /* anchor block handle */ 

HMQ hmq; /* message queue handle */ 

HWND hwndFrame, hwndClient; /* handles to windows */ 

QMSG qmsg; /* message */ 

char szClassNameE] = "Pointer Test 2"; 
char szWindowTitle[] = "Pointers"; 

ULONG f1FrameOpts = FCF_STANDARD & ~FCF_IC0N & 

~FCF_MENU & ~FCF_ACCELTABLE; 


hab = Winlnitialize(0); 

hmq = WinCreateMsgQueue(hab, 0); 

WinRegisterClass(hab, szClassName, ClientWndProc, 
CS_SIZEREDRAW, 0); 

hwndFrame = WinCreateStdWindow(HWND_DESKTOP, WS_VISIBLE, 

&flFrameOpts, szClassName, 
szWindowTitle, 0L, 0, 0, 
&hwndClient); 

while (WinGetMsg(hab, &qmsg, 0, 0, 0)) 

WinDispatchMsg(hab , &qmsg); 

Wi nDestroyWindow(hwndFrame); 

Wi nDestroyMsgQueue(hmq); 

WinTerminate(hab); 

return 0; 


MRESULT EXPENTRY ClientWndProc(HWND hwnd, ULONG msg, MPARAM mpl, 
MPARAM mp2) 

{ 

HPS hps ; 

RECTL rcl ; 

static HPOINTER hptr = NULLHANDLE; 

static HMODULE ptrlib = NULLHANDLE; 

/*event handler*/ 
switch(msg) { 

case WM_CREATE: 

if (DosLoadModule(NULL, 0, "PTRLIB.DLL", &ptrlib) ! = 
N0_ERR0R) 
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WinMessageBox(HWND_DESKTOP, HWND_DESKTOP, 
"Failed to load pointer library.", 
"Error!”, 0, MB_ERR0R | MB_CANCEL); 

return 0; 


case WM_PAINT: 

hps = WinBeginPaint(hwnd, NULLHANDLE, NULLHANDLE); 
WinQueryWindowRect(hwnd, &rcl ); 

WinFi11Rect(hps, &rcl , CLR_WHITE); 

WinEndPaint(hps ); 
return 0; 

case WM_BUTT0N1D0WN: 

if (ptrlib==NULLHANDLE) break; 

if (hptr) WinDestroyPointer(hptr); 

hptr = WinLoadPointer(HWND_DESKTOP, ptrlib, 1); 

Wi nSetPointer(HWND_DESKTOP, hptr) ; 
return 0; 

case WM_BUTT0N2D0WN: 

if (ptrlib==NULLHANDLE) break; 

if (hptr) WinDestroyPointer(hptr); 

hptr = WinLoadPointer(HWND_DESKTOP, ptrlib, 2); 

Wi nSetPointer(HWND_DESKTOP, hptr); 
return 0; 

case WM_M0USEM0VE: 

if (hptr) WinSetPointer(HWND_DESKTOP, hptr); 
return 0; 



case WM_DESTROY: 

DosFreeModule(ptrlib); 
return 0; 

} 

/*end event handlers */ 

return WinDefWindowProc(hwnd, msg, mpl, mp2); 

} 

Note the inclusion of the INCL_DOS define. 

The two new functions here are DosLoadModule and DosFreeModule: 

General: APIRET DosLoadModule(PSZ name, ULONG length, PSZ module, 
PHMODULE handle); 

As Used: if (DosLoadModule(NULL, 0, "PTRLIB.DLL", &ptrlib) != 
N0_ERR0R) 
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APIRET is an unsigned long integer, as you might have guessed. 

The first two parameters of DosLoadModule will contain information if the 
attempt to load the DLL failed for some reason. The return from DosLoad¬ 
Module will be something other than NO_ERROR if it failed. 

The more important parameters are the third, which specifies the filename of 
the DLL, and the fourth, which contains a pointer to the handle that you will 
use to reference the DLL. 

General: APIRET DosFreeModule(PHMODULE handle); 

As Used: DosFreeModule(ptrl ib); 

DosFreeModule is used to tell OS/2 that you’re done with the module. A mod¬ 
ule that has no clients will be unloaded from memory. 

You can use a loaded resource module with several of the functions covered 
in this book—specifically, anything that obtained a resource (bitmap, icon, 
pointer, menu, dialog, or whatever). If you look back, you’ll notice that every 
one of these calls had an HMODULE type parameter, which, up to this point, 
we left as NULLHANDLE. 

The POINTDLL program shows how a resource DLL can be used. If the user 
clicks mouse button 1, the first pointer is loaded (GRAB.PTR). If the user 
clicks mouse button 2, the second pointer is loaded (TARGET.PTR). 

hptr = WinLoadPointer(HWND_DESKT0P, ptrlib, 1); 

This is not particularly difficult to do, as you can see. But it can be quite 
useful. 


Conclusion 

So, all in all, despite my somewhat sarcastic comments at the beginning of 
this chapter, we must conclude that DLLs are A Good Thing. Certainly not the 
be-all, end-all of code re-use, but not without advantages. 

More importantly, however, every single Workplace Shell object is contained 
in its own DLL, and virtually every WPS program we build in the next part of 
this book will exist in a DLL that is invoked, in essence, by the Workplace 
Shell itself. In other words, the DLL becomes the final application—there is 
no executable! 


This is gonna be fun. 
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Threads and Semaphores 

in This Chapter 

Multitasking 

Sessions, processes, and threads 
Communication from threads 
Event semaphores 


Am 11 right, so the big buzzword of the ’90s is—well, pick one. Let’s 
w w rephrase that statement: What is it that OS/2 has that Windows 3.1 has 
not? A lot of things, of course, but one of the most easily identifiable and 
explainable features is multitasking. 


You’ll remember that I covered multitasking in the introduction to this book. 
It is, in essence, the capability of the operating system to make it appear as 
though several programs are running at the same time. I say “appear,” 
because most computers still have only one CPU and therefore the computer 
is really doing only one thing at a time. 


What the OS does is take a task that’s running and put it in a kind of box, 
telling the CPU to run what’s in that box. After some specified amount of time 
(determined by a complex set of priorities that we will not cover here), the 
OS takes the box out of the hot spot (where the CPU is actually executing its 
instructions) and puts in another box that contains another task. It does this 
quickly enough and frequently enough so that both programs appear to be 
running at the same time. 


This may suggest to you—rightly—that a multitasking system, by definition, 
is going to be slower than a single-tasking system. This is true. However, the 
benefit of being able to run several programs at once—not being locked in to 
a particular program—far outweighs the disadvantages in most cases. 

What we as programmers can appreciate about the process is that the OS 
creates the box for our tasks. We don’t have to worry, generally, about what 
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happens when the OS switches tasks. In fact, we don’t even have to do any¬ 
thing to keep our program from hogging the OS. OS/2 prevents this from hap¬ 
pening—except for one case, which we’ll talk about in a second. 

Now, however, it’s time to take a slightly more structured look at these 
“boxes.” There are, in fact, three kinds of “boxes” in OS/2, as shown in 
Figure 21-1. 


OS/2 




Legend: 

Figure 21-1: 

The OS/2 P Process 
"boxes." S Session 

miaEssmmm T Thread 



OS/2 Programming 101 

In the OS/2 Technical Library, the first recommended book is the Application 
Design Guide, and the first lesson in the Application Design Guide concerns 
sessions , processes , and threads. 
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We have dealt mostly with processes in this book up to this point. Any pro¬ 
gram we load is a process. The process includes the program and all of the 
program’s resources. Processes are protected from one another so that one 
cannot accidentally overwrite the memory or code of another. 



Processes can share resources, but the sharing must be done deliberately, 
through a number of techniques. 

Processes are the middle-sized box in Figure 21-1. The bigger box is the ses¬ 
sion. A session has its own virtual console. The virtual console is your screen, 
keyboard, and pointing device, logically set up so that everything doesn’t 
happen all at once. In other words, your full-screen OS/2 session dir com¬ 
mand doesn’t end up causing you to write over your Workplace Shell Desk¬ 
top. And typing d in that full-screen session doesn’t activate the LaunchPad’s 
Shut Down option. 


The “walls” between sessions are greater than the walls between processes. 
Theoretically, it would be harder for two processes in two different sessions 
to communicate with each other (or to adversely affect each other) than it 
would be for two processes in the same session. 



That’s why an OS/2 windowed program is different from an OS/2 full-screen 
program. By specifying an executable as NOWINDOWCOMPAT (see the dis¬ 
cussion of module definition files in Chapter 20), you are guaranteeing your 
program its own session, and hence greater isolation from other sessions. 


The DOS operating system is kind of weird in this respect. A DOS session can 
run either full screen or windowed on the PM Desktop, but it is still its own 
session. 


There are Dos* API calls under OS/2 to manage sessions and processes, but 
by far the most interesting and useful box for us is the smallest box—the 
thread. 



Threads contain the actual code that is executed by the CPU. Every process 
(every program ), therefore, has at least one thread. This makes sense when 
you think about it: Assuming that OS/2 or WPS has at least one thread of its 
own, if our program did not have a thread of its own, one would think that 
OS/2 or WPS had come to a halt (because our program would be monopoliz¬ 
ing the same thread that WPS or OS/2 used). 

The one thread that is always started as part of a process is called thread 1, 
or the main thread. If this thread is ended, the process is ended. 

Threads are not particularly insulated from other threads in the same 
process. Threads in the same process can easily share data (such as global 
variables, which you’re going to avoid using when programming OS/2, right?). 
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That also means that a rampant thread, careless of other threads in the 
process, can cause a program to go haywire by simply forgetting that there is 
one body of data used by everyone. (It’s an analogy for world peace.) Take a 
look at Figure 21-2. 



PROCESS 


A file opened by one thread can be read by any other thread in the system. 
The process uses a single heap from which all threads are allocated. 

The only private data the thread has is its stack. 


Coot Threads you Got There 

The key to working with threads is not getting them or using them, it’s man¬ 
aging them. Just as it’s important to avoid static variables in your PM pro¬ 
grams, it’s important to understand that having multiple threads is like 
having multiple programs running in the same data space. 

Having hammered that home, I hope, let’s look at the two calls we’ll use to 
create and destroy threads in this chapter: 
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General: APIRET DosCreateThreacK PTID ptid, PFNTHREAD pfn, ULONG 
param, ULONG opts, ULONG cbStack); 

As Used: if (DosCreateThread(&tid , pfn, hwnd, 0, 8192)!=N0_E RROR) 

General: APIRET DosKi 11 ThreaddID tid); 

As Used: DosKi11 Thread(tid) ; 


DosKillThread requires little explanation, I think. Just remember to kill any 
thread you start. 

DosCreateThread puts a thread ID in the first parameter, starts the thread 
executing the function specified in the second parameter, and passes the 
LONG in the third parameter to the function. 

The function must be defined using the _System directive we saw briefly in 
the last chapter (used with _DLL_InitTerm), and must have a single four-byte 
parameter and no return type: 

VOID _System threadfn(ULONG param) 

The function is given the amount of stack space specified in the last parame¬ 
ter, rounded up to the nearest even multiple of 4096. 

OS/2 allocates memory in pages of 4KB. It doesn’t deal with anything smaller 
or larger. This detail is usually hidden from us by our compilers, but if you’re 
interested you can use OS/2 Dos* calls to request memory directly from the 



I have never been able to get a thread to work with less than a 8192 stack 
size. If OS/2 is responding to your requests for threads with an error code, 
you might consider increasing the stack size. 

The options parameter (second to last) may be CREATE_READY or 
CREATE_SUSPENDED combined with either STACK_SPARSE or 
STACK_COMMITTED. 


A CREATE_READY thread starts going immediately after the DosCre¬ 
ateThread call is issued. A CREATE_SUSPENDED thread waits for a call to 
DosResumeThread to start executing: 

General: APIRET DosResumeThreacKTID tid); 

You can also suspend a thread after it starts executing by calling DosSus- 
pendThread: 

General: APIRET DosSuspendThreadCTID tid); 
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OS/2 generally reserves the right to not commit any memory until that mem¬ 
ory is actually requested by the thread. A thread created with the option 
STACKJSPARSE operates on that assumption. A STACK_COMMITTED thread 
forces OS/2 to commit all memory up front for the thread. (This could be 
faster if it is known in advance that all the memory is going to be used.) 

The default settings are CREATE_READY and STACK_SPARSE, so zero may be 
specified for the penultimate parameter of DosCreateThread. 


What can a thread do} 

What can you do with a thread once you have it? What are its limitations? 
What shouldn’t you do with a thread? The answers to these questions are 
easy to resolve if you realize that every single program we’ve written in this 
book has executed in a thread. 


In other words, even though we didn’t specifically request the thread, there 
really isn’t any difference between a thread we have created with DosCre¬ 
ateThread and the one that OS/2 provides for us. 


A thread can create its own window, and that window can call the main win¬ 
dow procedure or a different one. 



Remember that any global or static data will be shared, though. 

Also keep in mind that the HWND parameter passed to the window proce¬ 
dure allows you to paint (and otherwise act) on the correct window, so this 
is a feasible way to work with a second window of the same class as your 
main program window. 


Not all threads you create are going to be window threads—that is, threads 
with message queues— and this raises some important issues. 



I mentioned earlier that there is one situation that seems to grind the multi¬ 
tasking OS/2 to a halt. You can effectively stop user input to OS/2 by tying up 
your client window procedure. Simply don’t return from the procedure, and 
the user will be forced to kill the errant program through drastic means 
before being able to work with WPS again. 

During this time, however, OS/2 background tasks do continue. It is only user 
input that is blocked. 

This isn’t actually a thread issue, but a message queue issue. There is only 
one message queue in the current version of OS/2. Hence, if it is tied up, user 
input is stopped. 
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One of the reasons to add multiple threads to a program is to prevent that 
tie-up from occurring. For example, the user might want to count all the 
words in the current document, so you go through the entire file counting 
words, but you don’t want to tie up PM. 

Usually in such a case you won’t want your thread to have a message queue. 
However, if you don’t have a message queue, you can’t create a window, call 
a window’s client procedure, or do anything that might cause a window’s 
client procedure to be called. You have basically one means of communicat¬ 
ing with windows: 

General: BOOL WinPostMessage(HWND hwnd, ULONG cmd, MPARAM mpl, 
MPARAM mp2); 

As Used: WinPostMsg(cal 1er, WPLCOMMAND, MPFROMSHORT(CMD_D0NE), 0); 



WinPostMessage is very similar to WinSendMsg, as you can see, but differs in 
one important respect: WinSendMsg sends a message to a window and waits 
for that message to be answered. 

This should make sense to you if you read the chapters on controls (Chap¬ 
ters 11 through 17) because the programs all relied on acting upon the vari¬ 
ous windows’ answers to messages sent via WinSendMsg. 


WinPostMessage, on the other hand, simply posts the message to the win¬ 
dow’s message queue, or returns FALSE if it can’t post the message for what¬ 
ever reason—such as a full window message queue. 


WinPostMessage doesn’t wait around to find out what the answer to the mes¬ 
sage is, which is also good for an independent thread that might be posting 
progress messages to a window that may or may not be able to act on them 
right away. Even if the window doesn’t act on the message, the thread keeps 
going. 



One important thing to remember about WinPostMessage is that, even if the 
application doesn’t have a message queue or a window, it must have 
requested PM’s services through the Winlnitialize call. (It should then call 
WinTerminate when done.) We’ll see this in action now. 

This is not the only way a non-window thread can communicate with a win¬ 
dow, as we’ll see later on. 


The Thread program 

We’re now in a position to look at some source code that employs multi¬ 
threading. Here is THREAD.C: 
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//define INCL_D0S 
//define INCL_GPI 
//define INCL„WIN 
^include <os2.h> 

#inelude <string.h> 

#include "thread.h" 

MRESULT EXPENTRY ClientWndProc(HWND, ULONG, MPARAM, MPARAM); 
VOID _System countfn(LONG param); 

#define APPNORMAL 0 
#define INITFAILURE -1 
#define USERQUIT -2 

typedef struct { 

LONG passes; 

LONG progress; 

BOOL update; 

BOOL done; 

} SHARED; 

typedef SHARED *PSHARED; 


int main (void) 


HAB 

hab; 

/* 

anchor i 

bl ock 

handl e 

*/ 

HMQ 

hmq; 

/* 

message 

queue 

handle 

*/ 

HWND 

hwndFrame, hwndClient; /* 

handles 

to windows 

*/ 

QMSG 

qmsg; 

/* 

message 



*/ 

char 

szClassName[] = " 

Mul tithreading 1 ! ! 

INI"; 



char 

szWindowTitle[] = 

"Thread 

It, Baby 

1 " ; 



ULONG 

f1FrameOpts = FCF 

.STANDARD 

; 





ULONG appState = APPNORMAL; 

PSHARED wd; 

hab = Winlniti al i ze(0); 

hmq = Wi nCreateMsgQueue(hab, 0); 

if (!WinRegisterClass(hab, szClassName, ClientWndProc , 
CS_SIZEREDRAW, 4)) 
appState = INITFAILURE; 

hwndFrame = WinCreateStdWindow(HWND.DESKTOP, WS_V I S IBLE , 

&f1FrameOpts, szClassName, 
szWindowTitle, 0L, 0, 
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THREADPROGRAMID, 

&hwndClient); 

wd = (PSHARED)malloc(sizeof(SHARED)); 

wd->done = FALSE; 

wd->update = FALSE; 

wd->progress = 0; 

wd->passes = 0; 

WinSetWindowPtr(hwndClient, 0, wd); 

if ((appState==INITFAILURE) || (hab==NULLHANDLE) || 

(hmq==NULLHANDLE) || (hwndFrame==NULLHANDLE)) 

WinMessageBox(HWND_DESKTOP, HWND_DESKT0P, 

"Unable to initialize application.", "ERROR!", 

0, MB_CANCEL | MB_ERR0R); 

el se 

while (appState==APPNORMAL) { 

while (WinGetMsg(hab, &qmsg, 0, 0, 0)) 

WinDispatchMsg(hab, &qmsg); 

if (WinSendMsg(hwndClient, WM_COMMAND, 

MPFR0M2SH0RT(CMD_VERIFY, 0), 0) != MBID_CANCEL) 
appState = USERQUIT; 

if (qmsg.hwnd == NULLHANDLE) /^system shutdown */ 

if (appState != USERQUIT) WinCancelShutdown(hmq, FALSE); 


WinDestroyWindow(hwndFrame); 
WinDestroyMsgQueue(hmq); 

WinTerminate(hab); 

return 0; 

} 


MRESULT EXPENTRY ClientWndProc(HWND hwnd, ULONG msg, MPARAM mpl, 
MPARAM mp2) 


HPS 

hps ; 

RECTL 

rcl ; 

ULONG 

cmd; 

TID 

ti d; 

PFN 

pfn = &countfn 

char 

text[1000]; 
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PSHARED wd; 

/*event handler*/ 
switch(msg) { 

case WM_PAINT: 

wd = WinQueryWindowPtr(hwnd, 0); 

hps - WinBeginPaint(hwnd, NULLHANDLE, NULLHANDLE); 

WinQueryWindowRect(hwnd, &rcl); 

WinFi11Rect(hps, &rcl , CLR_WHITE); 
if (wd->update) { 

sprintf(text, "Progress: %d", wd->progress); 

GpiSetBackMix(hps, BM_OVERPAINT); 

WinDrawText(hps, -1, text, &rcl, 0,0, 
DT_TEXTATTRS | DT_CENTER | DT_VCENTER); 
wd->update = FALSE; 

} 

WinEndPaint(hps); 
return 0; 


case WM_COMMAND: 

switch(SHORTlFROMMPCmpl)) { 

case CMD_PROGRESS: 
wd = WinQueryWindowPtr(hwnd, 0); 
wd->progress = SH0RTlFR0MMP(mp2); 
wd->update = TRUE; 

WinlnvalidateRect(hwnd, NULL, 0); 
return 0; 

case CMD_D0NE: 

WinMessageBox(HWND_DESKTOP, HWND_DESKTOP, 

"Finished!", "Information!", 

0, MB_0K | MB_INFORMATION); 
return 0; 

case CMD_FILEDOIT: 

if (DosCreateThread(&tid, pfn, hwnd, 0, 8192)1=0) 
WinMessageBox(HWND_DESKTOP, HWND_DESKTOP, 

"Unable to create thread.", "ERROR!", 

0, MB_CANCEL | MB_ERR0R); 
return 0; 

case CMD_VERIFY: 
cmd = MBID_N0; 
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/* if (data_modified) */ { 

cmd = WinMessageBox(HWND_DESKTOP, hwnd, 

"Do you want to save your work before exiting?", 
"Query", 0, MB_YESNOCANCEL | MB_QUERY); 

/* if cmd==MB_YES save_data */ 

} 

return (MRESULT)cmd; 

/* case CMD_OTHERCOMMANDS: */ 

} /* end WM_COMMAND messages */ 

} /*end event handlers */ 
return WinDefWindowProc(hwnd, msg, mpl, mp2); 

} 


VOID _System countfn(HWND caller) 
{ 

LONG counter = 0; 

HAB hab = Winlnitialize(hab); 


whi1e(counter < 5000) { 
counter = counter + 1; 
if (counter % 100 == 0) { 

WinPostMsg(cal 1er, WM_COMMAND, 
MPFROMSHORT(CMD_PROGRESS), 
MPFROMSHORT(counter)); 


WinPostMsg(caller, WM_COMMAND, MPFROMSHORT(CMD_D0NE), 0); 
WinTerminate(hab); 


This program is based on the BASIC2.C program, as you can see, with just a 
few minor changes to the .H and .RC files: 

#define THREADPROGRAMID 1000 


//define CMD_HELP 1001 
//define CMD_VERI FY 1002 
//define CMD_D0NE 1003 
//define CMD_PROGRESS 1004 

//define MID_FILE 2000 
//define CMD_FI LEOPEN 2001 
//define CMD_FI LEDOIT 2002 


The .RC file includes the extra “Do It” menu item: 
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//include <os2.h> 

//include "thread, h" 

ICON THREADPROGRAMID mahjongg.ico 

MENU THREADPROGRAMID 
BEGIN 

SUBMENU "-File",MID_FILE 
BEGIN 

MENUITEM "~Open\tCtrl+0",CMD_FILEOPEN 
MENU ITEM SEPARATOR 
MENUITEM "-Do It\tF2",CMD_FILEDO IT 
END 
END 


ACCELTABLE THREADPROGRAMID 
BEGIN 

VK_FI, CMD_HELP, VIRTUALKEY, HELP 

VK_F2, CMD_FILEDOIT, VIRTUALKEY 
END 


As you can see, the window responds to CMD_PROGRESS and to CMDJDONE 
messages posted from the thread just as it does to any other message. The 
actual progress being made is tucked into mp2—much as a control window 
might work. 



You may want to experiment with this loop to see the effects of requesting 
that the window update itself frequently: 

whi1e(counter < 5000) { 

counter = counter + 1; 
if (counter 1 100 == 0) { 

WinPostMsg(cal 1er, WM_C0MMAND, 

MPFROMSHORT(CMD_PR0GRESS), 

MPFROMSHORT(counter)); 

} 


What happens, for example, if you send CMD_PROGRESS every iteration 
instead of every hundredth iteration? 

Note that even though the parameter to a thread function is described as a 
ULONG, a four-byte value can be passed. In general, as long as the threads 
are in the same process (as they always will be in the examples in this chap¬ 
ter), you’ll probably want to pass a pointer containing data that the two 
threads can use to communicate with each other. 
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So, even though I used the message structure (mpl and mp2) to communi¬ 
cate with the calling thread, I could have changed the data directly in the 
window’s data structure and sent the calling window a WM_PAINT message. 

This is perfectly acceptable, but the approach shown is more generally useful 
since it isn’t tied to the window repainting itself. 

The Semaphore (It Beats a 
Smoke Signal) 

OS/2 has a means of interprocess, interthread, and even intersession commu¬ 
nication. We’re going to look at one of those methods, called the semaphore. 
An OS/2 semaphore is a way for one thread to signal another that something 
is happening. 

The dictionary defines a semaphore as “any method used for signaling.” That 
fits. I think of them as flags—you run them up the flag pole and...Is anyone 
saluting? 

Semaphores come in several varieties, the more complex being those 
designed to prevent several threads from accessing the same shared 
resources at the same time. You might want to restrict access to memory 
that is being written to, for example. 

The kind of semaphore we’re going to look at is called an event semaphore. 
There are six functions used to manage event semaphores, which we will 
cover in turn. 

General: APIRET DosCreateEventSem(PSZ name, PHEV sem, ULONG opts, 
B00L32 state); 

As Used: if (DosCreateEventSem(NULL, &(wd->sem2), 0, 0) ! = 

D0S_ERR0R) 

This function call creates an event semaphore with the name specified in the 
first parameter, and returns a handle to it in the second parameter. The name 
is optional, but threads that don’t have direct access to the handle can 
request a semaphore by name. Semaphore names must begin with \SEM32\ 
and must be valid filenames. 

An event semaphore can be created with one option, DC_SEM_SHARED, 
which means that it can be used by other processes. If the state parameter is 
FALSE, the semaphore is created “set” (down the flagpole). If state is TRUE, 
the semaphore is created “posted” (up the flagpole). 



312 PartIV Polish and Panache 


HEV, by the way, is a 32-bit integer. The name is presumably short for handle 
to event semaphore. 

General Form: APIRET DosCloseEventSem(HEV sem); 

As Used: DosCloseEventSem(wd->seml); 

Many threads access the same semaphore. (That’s the whole idea.) After a 
thread is done with a semaphore it should “close” it. When all threads have 
closed the semaphore, OS/2 destroys it. (Or folds it up and puts it away for 
the night, if you prefer to stick with the flag analogy.) 

General Form: APIRET DosPostEventSem(HEV sem); 

As Used: Dos Post EventSem(wd->seml); 

This sets the flag a-waving. But one way that a semaphore differs from an 
actual flag is that a semaphore keeps count of how many times it has been 
posted: 

General Form: APIRET DosQueryEventSemCHEV sem, PULONG posts); 

As Used: DosQueryEventSem(wd->seml, &posts); 

DosQueryEventSem returns the number of times a semaphore has been 
posted since it was last reset in the second parameter. 

General Form: APIRET DosResetEventSem(HEV sem, PULONG posts); 

As Used: DosResetEventSem(wd->seml, &posts); 

DosResetEventSem is functionally the same as DosQueryEventSem, except 
that it also resets the event semaphore’s post count to zero. 

General Form: APIRET DosOpenEventSem(PSZ name, PHEV sem); 

DosOpenEventSem opens the event semaphore having the name in the first 
parameter or the handle matching the second parameter. We won’t be using 
this in the example program because any thread in the process that created 
the semaphore has immediate access to the semaphore. 

Now it’s time to look at some sample code to illustrate the use of event sema¬ 
phores. 

Othello Versus the Semaphores 

The following program displays the opening words of Shakespeare’s Othello, 
with the following twist: The text is in a thread and the thread copies the text 



Chapter 21 Threads and Semaphores 


313 


in increasing amounts every few milliseconds. (Imagine the thread is pro¬ 
cessing a file.) 

When it increments the amount of output, it posts a semaphore. When it is 
finished with the entire text, it posts a different semaphore. 

When the calling program’s event handler isn’t doing anything else, it queries 
the semaphores to see if the process is done or how much progress has been 
made. 

If the process is complete, the window sends itself a CMD_DONE command, 
which it handles by closing the event semaphores and notifying the user. 

If progress has been made, the window sends itself a CMD_PROGRESS mes¬ 
sage that invalidates the window, forcing a repaint. 

This creates the effect of the text scrolling across the screen. The interesting 
thing about this is that if no events get passed to the window—say the user is 
off in some other window or is just not doing anything—the thread contin¬ 
ues, but the window never checks on it. 

So, to i eally get the scrolling effect, you have to hold down a key or jiggle the 
mouse back and forth over the window. This is an important point, because if 
you expect to use semaphores with a progress indicator, you’ll need to set up 
a timer to force periodic checks on the semaphore. 

The code listed here uses the THREAD.H and THREAD.RC files. The thread is 
started by the CMD_FILEDOIT command as before, but in this case the com¬ 
mand is disabled when the thread starts and is not reenabled until the thread 
has finished. 

The complete Othello text that I used appears after the listing, because it was 
too long to show as I wrote it in the program. 

//define INCL_D0S 
//define INCL_GPI 
//define INCL_WIN 
//include <os2.h> 

//include <string.h> 

//include "thread, h" 

MRESULT EXPENTRY ClientWndProc(HWND, ULONG, MPARAM, MPARAM); 

VOID _System countfn(LONG param); 


//define APPNORMAL 
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#define INITFAILURE -1 
//define USERQUIT -2 


typedef 

struct { 

LONG 

passes; 

LONG 

progress; 

BOOL 

update; 

BOOL 

done; 

PSZ 

text; 

HEV 

semi, sem2 

BOOL 

ip; 

} SHARED; 


typedef SHARED *PSHARED; 


int main 

(void) 




{ 

HAB 

hab; 

/* 

anchor block handle 

*/ 

HMQ 

hmq; 

/* 

message queue handle 

*/ 

HWND 

hwndFrame, hwndClient; 

/* 

handles to windows 

*/ 

QMSG 

qmsg; 

/* 

message 

*/ 


char szClassName[] = "Multithreading!!!!!!!"; 
char szWindowTitle[] = "Thread It, Baby!"; 

ULONG flFrameOpts = FCF_STANDARD; 

ULONG appState = APPNORMAL; 

PSHARED wd; 

hab = Winlnitialize(0); 

hmq = WinCreateMsgQueue(hab, 0); 

if (!WinRegisterClass(hab, szClassName, ClientWndProc, 
CS_SIZEREDRAW, 4)) 
appState = INITFAILURE; 

hwndFrame = WinCreateStdWindow(HWND_DESKTOP, WS_VISIBLE, 

&flFrameOpts, szClassName, 
szWindowTitle, 0L, 0, 
THREADPROGRAMID, 

&hwndClient); 

wd = (PSHARED)mal1oc(sizeof(SHARED)); 

wd->done = FALSE; 

wd->update = FALSE; 

wd->progress = 0; 

wd->passes = 0; 

wd->text = (PSZ)mal1oc(1000); 
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wd->seml = 0; 
wd->sem2 = 0; 
wd->ip = FALSE; 

WinSetWindowPtr(hwndClient, 0, wd); 

if ((appState==INITFAILURE) || (hab==NULLHANDLE) || 

(hmq==NULLHANDLE) || (hwndFrame==NULLHANDLE)) 
WinMessageBox(HWND_DESKTOP, HWND_DESKTOP, 

"Unable to initialize application.", "ERROR!", 

0, MB_CANCEL | MB_ERR0R); 

el se 

while (appState==APPNORMAL) { 

while (WinGetMsg(hab, &qmsg, 0, 0, 0)) 

WinDispatchMsg(hab, &qmsg); 

if (WinSendMsg(hwndClient, WM_COMMAND, 

MPFR0M2SHORT(CMD_VERIFY, 0), 0) ! = MBID_CANCEL) 
appState = USERQUIT; 

if (qmsg.hwnd == NULLHANDLE) /^system shutdown */ 

if (appState ! = USERQUIT) WinCancelShutdown(hmq, FALSE); 


WinDestroyWindow(hwndFrame); 
WinDestroyMsgQueue(hmq); 

WinTerminate(hab); 

return 0; 

} 


MRESULT EXPENTRY ClientWndProc(HWND hwnd, 
MPARAM mp2) 


ULONG msg, MPARAM mpl, 


H PS 

RECTL 

ULONG 

TID 

PFN 

PSHARED 

ULONG 


hps ; 
rcl ; 
cmd; 
ti d; 

pfn = &countfn; 
wd; 


posts; 


FONTMETRICS fm; 

int charHeight, len, written; 

/^event handler*/ 
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switch(msg) { 
case WM_PAINT: 

wd = WinQueryWindowPtr(hwnd , 0); 

hps = WinBeginPaint(hwnd, NULLHANDLE, NULLHANDLE); 

WinQueryWindowRect(hwnd, &rcl ); 

if (!wd->update) WinFi11Rect(hps, &rcl , CLR_WHITE); 
el se { 

GpiQueryFontMetricsChps, sizeof(fm), &fm); 
charHeight = fm.1MaxBaselineExt; 
rcl.yBottom = rcl.yTop-charHeight; 

1en = strlen(wd->text); 

written = 0; 

while (written < len) { 

written = written + WinDrawText(hps, -1, wd->text+written, 
&rcl , 0, 0, DT_TEXTATTRS | DT_WORDBREAK | 

DT_ERASERECT); 

rcl.yTop = rcl.yTop - charHeight; 

rcl.yBottom = rcl.yBottom - charHeight; 

if (rcl.yBottom < 0) break; 

} 

wd->update = FALSE; 

} 

WinEndPaint(hps); 
return 0; 


case WM_COMMAND: 

wd = WinQueryWindowPtr(hwnd, 0); 
switch(SHORTlFROMMP(mpl)) { 

case CMD_PROGRESS: 
wd->update = TRUE; 

WinlnvalidateRect(hwnd, NULL, 0); 
DosResetEventSem(wd->seml, &posts); 
return 0; 

case CMD_D0NE: 

wd = WinQueryWindowPtr(hwnd, 0); 
wd->ip = FALSE; 

WinMessageBox(HWND_DESKTOP, HWND_DESKTOP, 
"Finished!", "Information!", 

0, MB_0K | MB_INFORMATION); 

DosCloseEventSem(wd->seml); 

DosCloseEventSem(wd->sem2); 

WinSendMsg( 




WinWindowFromID(hwnd, THREADPROGRAMID), 
MM_SETITEMATTR, 

MPFROMSHORT(CM D_FILEDO IT), 

MPFR0M2SH0RT(MIA_DISABLED, 0) ) ; 
return 0; 

case CMD_FILEDOIT: 

wd = WinQueryWindowPtr(hwnd, 0); 

if (DosCreateEventSem(NULL, &(wd->seml), 0, 0) != 0) { 
WinMessageBox(HWND_DESKTOP, HWND_DESKTOP, 

"Unable to create progress semaphore.", "Error! 
0, MB_CANCEL | MB_ERR0R); 
break; 

} 

if (DosCreateEventSemCNULL, &(wd->sem2), 0, 0) != 0) { 
WinMessageBox(HWND_DESKTOP, HWND_DESKTOP, 

"Unable to create finished semaphore.", "Error! 
0, MB_CANCEL | MB_ERR0R); 

DosCloseEventSem(wd->seml); 
break; 

} 

if (DosCreateThread(&tid, pfn, hwnd, 0, 8192) != 0) { 

WinMessageBox(HWND_DESKTOP, HWND_DESKTOP, 

"Unable to create thread.", "ERROR!", 

0, MB_CANCEL | MB_ERR0R); 
break; 

1 

WinSendMsg( 

WinWindowFromlD(hwnd, THREADPROGRAMID), 
MM_SETITEMATTR, 

MPFROMSHORT(C M D_ FILEDOIT), 

MPFR0M2SHORT(MIA_DISABLED, MIA_DISABLED)); 
wd->ip = TRUE; 
return 0; 

case CMD_VERIFY: 
cmd = MBID_N0; 

/* if (data_modified) */ { 

cmd = WinMessageBox(HWND_DESKTOP, hwnd, 

"Do you want to save your work before exiting?", 
"Query", 0, MB_YESNOCANCEL | MB_QUERY); 

/* if cmd==MB_YES save_data */ 

1 

return (MRESULT)cmd; 

/* case CMD_OTHERCOMMANDS: */ 


} /* end WM_COMMAND messages */ 
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default: 

wd = WinQueryWindowPtr(hwnd, 0); 
if (wd==NULL) break; 
if (wd->ip) { 

DosQueryEventSem(wd->sem2, &posts); 
if (posts>0) { 

WinPostMsg(hwnd, WM_COMMAND, MPFR0MSH0RT(CMD_D0NE), 0); 
break; 

} 


/* don’t bother to check the progress semaphore, 
if the done semaphore has been signalled */ 

DosQueryEventSem(wd->seml, &posts); 
if (posts>0) 

WinPostMsg(hwnd, WM_COMMAND, MPFR0MSH0RT(CMD_PROGRESS), 
0 ); 


break; 

} /*end event handlers */ 


return WinDefWindowProc(hwnd, msg, mpl, mp2); 


VOID _System countfn(HWND caller) 

{ 

LONG counter = 0; 

PSHARED wd; 

PSZ text = "\tRodrigo\nTush! never tell me..." /*see below*/ 

wd = WinQueryWindowPtr(cal 1er, 0); 
whi1e(counter < strlen(text)) { 

DosSleep(50); 

counter = counter + 1; 

strncpy(wd->text, text, counter); 

DosPostEventSem(wd->seml); 

1 


DosPostEventSem(wd->sem2); 
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And the text: 

Rodrigo: 

[Tush!] never tell me; I take it much unkindly 

That thou, Iago, who has had my purse 

As if the strings were thine, shouldst know of this. 

Iago: 

[’Sblood], but you will not hear me. 

If ever I did dream of such a matter, 

Abhor me, 

Rodrigo: 

Thou told’st me thou didst hold him in thy hate. 

Iago: 

Despise me, if I do not. Three great ones of the city, 

In personal suit to make me his lieutenant, 

Off-capp’d to him; and, by the faith of man, 

I know my price; I am worth no worse a place. 

Conclusion 

You have a great deal under your belt by now. In fact, you have all the pure 
Presentation Manager information you’re going to get from this book, and PM 
is where a lot of books—and a lot of programs—stop. 

The fun is just beginning. Now we explore the most advanced graphical user 
interface of any popular OS. And you may be surprised just how easy it is to 
use. 

But first, a few stupid WPS tricks to dazzle your friends and astound your 
enemies. 



Chapter 22 

Stupid WPS Tricks 

In This Chapter 

fe Programmatically manipulating WPS objects 
Querying WPS classes 
REXX command files 
The LaunchPad 


f m very good OS/2 application, WPS or not, is expected to set up a folder 
»when installed. The folder should contain objects representing all the 
crucial elements of the application, arranged in a meaningful fashion. 


So, although the title of this chapter is “Stupid WPS Tricks,” rest assured that 
these tricks, while easy, are also quite important. And they will give you a feel 
for what WPS is and how it works, which will help you quite a bit in the next 
part. 


We’re also going to take a break from the grueling C compile-link develop¬ 
ment cycle we’ve used up to this point to look at some easy ways to manipu¬ 
late Workplace Shell objects. (Instant gratification time!) 


REXX and the Workplace Shell 

Our explorations of these WPS functions will be done through REXX, OS/2’s 
batch-language-on-steroids. 

If you don’t know REXX, you should. REXX is kind of like BASIC or DOS’s 
batch file language. It takes about a day to learn and is immensely useful. - 

You’ll be able to read and reproduce these REXX samples easily, even if 
you’ve never used REXX before, as long as you keep a few things in mind: 




322 Part SV Polish and Panache ____ 

v 0 REXX programs always start with a comment, which is enclosed in /* */, 
like traditional C. This comment distinguishes from OS/2 batch files. 

v* All REXX program variables are strings, hence they never are declared 
| or defined anywhere. 

REXX is not case sensitive. 

v* There are two means of calling a function in REXX. When you want to 
ignore the function’s results, you use “call function parml, parm2, 
i parm3.” When you are interested in the function results, you use a form 
like “if function(parml, parm2, parm3).” 

All of REXX’s superpowers are obtained by loading function libraries. 

The following two lines give REXX all the power it needs to interact with 
■ WPS: 

call RxFuncAdd 'SysLoadFuncs ' , 'RexxUtil', 'SysLoadFuncs' 
call SysLoadFuncs 

In REXX (like BASIC), if a statement is going to extend beyond a single 
i: physical line, you use the code continuation character, which is a 

comma. 

* 1 v* Lastly, all the REXX functions are equivalent to similarly named OS/2 API 
| functions. SysCreateObject in REXX is equivalent to WinCreateObject in 
1 the API. So you can translate the following into C, Pascal, or whatever 
accordingly. To do this, keep in mind that the API returns an object han- 
| die (HOBJECT) where REXX always uses a string that identifies the 
$ object. 

1 

Object Identifications 

Some objects in the Workplace Shell have IDs. If you know the object’s ID, 
you can access it. You can find out about it, change it, copy it, even delete it 
if you so choose. 

IDs are also important because they identify places for you to put things. If 
you want to create a folder on the Desktop, for example, you have to know 
the ID of the Desktop. The object IDs in Table 22-1 are predefined. 
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Table 22-1 WPS Locations 

identifier 

Appears on Desktop as 

<WP_C0NFIG> 

System Setup folder 

<WP_DESKTOP> 

Desktop 

<WP_DRIVE> 

Drives folder 

<WP_INF0> 

Information folder 

<WP_NOWHERE> 

Hidden folder 

<WP_START> 

Startup folder 

<WP_SYSTEM> 

System folder 

<WP_TEMPS> 

Templates folder 


(I’ll bet you didn’t even know there was a hidden folder!) 

You may be thinking that there is a difference between the objects on your 
Desktop and the objects that come up when you open a drive object. There 
isn’t. 



If you don’t know the object’s ID, you can specify the physical path of the 
object. So, you could refer to your CONFIG.SYS file as C:\CONFIG.SYS and 
manipulate it as you would any other WPS object, except perhaps more care¬ 
fully. 

A WPS object ID is always shown surrounded by angle brackets, which means 
that it can never be a valid filename, and therefore can never be confused 
with an object that is specified by its filename. 



If you expect to manipulate an object that you have created, you must be pre¬ 
pared to give the object an ID. You will use that ID in all future calls. 

In C and other API-aware languages, the creation of the object results in the 
code being passed an object handle that can be used for the duration of the 
program. 


Of course, you then have the problem of identifying the object in a later pro¬ 
gram if you haven’t assigned a specific ID. 
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Creating and Opening Folders 
(and Other Objects) 


Any OS/2 application is likely to consist of one or more programs, some data 
files, and perhaps references to files or programs it expects to find on the 
user’s disk. So, let’s look at the steps required to create such a folder: 


Always start with a comment and the following lines: 


/* A REXX PROGRAM */ 

call RxFuncAdd 'SysLoadFuncs', ' Rexxlltil', 'SysLoadFuncs' 
call SysLoadFuncs 

to allow your REXX program to interact with WPS. m 

The function that creates an object is SysCreateObject, which has a maxi¬ 
mum of five parameters, including the type (or class) of the object being cre¬ 
ated, the title of the object as it will appear in WPS, and the location of the 
object. 





WPS classes 


A minimal Workplace Shell installation con¬ 
tains a fair number of object classes. Here 
are some of the classes you're most likely to 
be interested in: 


WPBitmap 
WPDataFi1e 
WPFolder 
WPLaunchPad 


WPColorPalette 

WPDesktop 

WPFontPalette 

WPMinWinViewer 


WPCommandFi1e 


WPPointer WPPrinter WPProgram 

WPProgramFile WPSchemePalette WPShadow 
WPShredder WPSound 

You may not have even considered that some 
of these objects could be recreated, but in 
fact, they can. You can even provide your 
own customized launchpad, so that the user 
can have it available when working with your 
programs and tuck it away when done. 


But even so, these represent only a fraction 
of the total classes available on any given 
system. The other ones are not as useful as 
these for generic purposes, of course, but if 
you should ever wonder what those classes 
are, use SysQueryClasses to list all the 
classes on a system: 

/* Lists all classes */ 
call RxFuncAdd 'SysLoadFuncs', 'RexxU¬ 
til', 'SysLoadFuncs' 
call SysLoadFuncs 
call SysQueryClassList "Classes." 
do i = 1 to Classes.0 
say classes.i 
end 
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The fourth parameter to SysCreateObject is called the setup string , and 
defines how the object will be created. The setup string can be rather 
involved, and we will look at how involved later. For now, just recognize that 
it can be used to set the object ID by specifying OBJECTID=<objid>. This 
parameter is optional. 

The fifth parameter is either “fail,” “replace,” or “update,” or rather f, r, or u. 
This parameter determines what happens if the object already exists on the 
Desktop. With f, the default, the call fails. If you specify r, the created object 
replaces the existing one. If you specify u, the existing object is updated to 
match the settings passed. 

The call itself is probably easier to read and understand than the explana¬ 
tion: 



if \SysCreateObject("WPFolder", "0S2 Warp Programming",, 

"<WP_DESKTOP>", "0BJECTID=<0WP4D_Folder>"), 
then say "Folder create failed." 

Note the comma line-continuation characters. 

Also, a backslash in REXX means “not.” SysCreateObject will return 1 if the 
call is successful, or 0 otherwise. 


I used a common naming scheme for WPS objects in this example: a prefix fol¬ 
lowed by an underscore, followed by the name of the specific object. 

You can open any object you have an ID for with SysOpenObject, which takes 
three parameters: the object ID, the kind of view to open, and an indication of 
whether to open a new view or to bring an existing view to the surface. 

The second parameter is one of the following: Contents, Default, Details, Set¬ 
tings, or Tree. If the third parameter is FALSE, and a view of the object is 
already open, a call to SysCreateObject opens another view. 

Having created the folder with the last call, this one would open it: 



if \SysOpenObject("<0WP4D_Folder>","I con",TRUE), 
then say "Folder open failed." 

SysOpenObject may be used with any WPS object, not just folders. The 
resulting behavior will be exactly the same as if the user had opened it. So 
you could use this call to run programs. 
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Creating a Program Object and Icon 

Having created and opened a folder, we might now want to create a program 
file to go inside it. For this example, let’s use the HELLO.EXE file. 

Before looking at how to create this object, though, let’s look at another fea¬ 
ture you can use to associate an icon with a file, called SysSetlcon. 

SysSetlcon takes two parameters: The first is the path of the file whose icon 
you want to set; the second is the path of the icon file. 

if \SysSetIcon("C:\SOURCE\HELLO.EXE", , 

"C:\SOURCE\TESTICO.ICO") ; 
then say "Icon association failed." 

You’ll have to replace C:\SOURCE in the preceding example with the direc¬ 
tory you used for your code. 

This version of SysCreateObject is going to expand our understanding of 
what can appear in the setup string parameter: 

if \SysCreateObject("WPProgram", "Hello Word d","<0WP4D_Folder>",, 
"OBJECUD=<OWPDR_Hel 3 o> ;" | | , 

"EXENAME=C:\S0URCE\HELL0.EXE") , 

then say "Hello create failed." 

So for a program object, besides an OBJECT1D, you can specify the “EXE- 
NAME” for the program object—something you would usually want to do. 

Let’s take a closer look at the setup string now. 


Setup Strings and Object Bata 

Ignoring the I I for the moment, which is REXX’s string concatenation opera¬ 
tor, a WPS object’s setup string looks like this: 

key=value;key=value;key=value 

The trick to setting up an object, then, is knowing what the key names are, 
and what the valid values for those key names can be. Tables 22-2, 22-3, and 
22-4 list the keys and values for WPObject, WPFolders, and WPPrograms 
respectively. 
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In the following tables, when you see an x,y value in a WPS object’s settings, 
that value represents a percentage of the screen. So 25,25 is not “25 pixels up 
from and 25 pixels to the right of” the bottom left-hand corner of the screen; 
rather, it is “1/4 of the way up and to the right.” 


When a filename is requested, you can use ?:\ to indicate the boot drive. 


Table 22-2 WPObject's Keys and Values 

WPObject Keys 

Values Allowed 

CCVIEW 

YES, NO, DEFAULT 

HELPLIBRARY 

.HLP file 

HELPPANEL 

Help panel ID 

HIDEBUTTON 

YES, NO 

ICONFILE 

Filename 

ICONPOS 

x,y (percentage) 

1C0NRES0URCE 

ID .DLL name 

M INWIN 

HIDE, DESKTOP 

NOCOPY 

YES, NO 

NODELETE 

YES, NO 

NODRAG 

YES, NO 

NODROP 

YES, NO 

NOLINK 

YES, NO 

NOMOVE 

YES, NO 

NORENAME 

YES, NO 

NOSHADOW 

YES, NO 

NOTVISIBLE 

YES, NO 

OBJECTID 

<objectid> 

OPEN 

SETTINGS, DEFAULT 

TEMPLATE 

YES, NO 

TITLE 

Object title 
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Table 22-3 WPFolder s Keys and Values 

WPFolder Keys 

Values Allowed 

ICONFONT 

Font name 

TREEFONT 

Font name 

DETAILS FONT 

Font name 

ICONVIEW 

MINI, INVISIBLE, NONFLOWED, FLOWED 

TREEVIEW 

MINI, INVISIBLE, NOLINES 

DETAILS VIEW 

MINI, INVISIBLE 

ICONVIEWPOS 

x, y, cx, cy (percentage) 

BACKGROUND 

Background bitmap file 

WORKAREA 

YES, NO 

REMOVEFONTS 

YES, NO 

OPEN 

ICON, DETAILS, TREE 


Table 22-4 WPProgram's Keys and Values 


WPProgram Keys 

Values Allowed 

PROGTYPE 

Program type (choices listed after this table) 

EXENAME 

Program filename 

PARAMETERS 

Parameters passed to program 

STARTUPDIR 

Startup directory 

SET 

SET A=B; SET C=D (environment variables) 

NOAUTOCLOSE 

YES, NO 

MINIMIZED 

Start minimized 

MAXIMIZED 

Start maximized 

ASSOCFILTER 

File extensions to associate (such as * TXT) 

ASSOCTYPE 

File types to associate (such as Plain Text) 
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If the file type specified for ASSOCTYPE does not exist, it will be created—so, 
watch your spelling! (This is also true of the WPProgramFile object that we’ll 
look at shortly.) 


The Program type can be any of the following: FULLSCREEN, WINDOW- 
ABLEVIO, VDM, WINDOWEDVDM, SEPARATEWIN, WINDOWEDWIN, WIN, or 
PM. Or, if it’s a Windows program and you want to get really specific about 
what kind of Windows program, you can use any of these: PROG_31_STD- 
SEAMLESSVDM, PROG_31_STD, PROG_31_STDSEAMLESSCOMMON, 
PROG_30_STD, PROG_31_ENHSEAMLESSVDM, PROG_31_ENH, or 
PROG_31_ENHSEAMLESSCOMMON. 


Finally, if you’ve created a program, you’ll want to be able to create program 
files for it, which you can do with the WPProgramFile class. This class has 
only two new keys, as shown in Table 22-5. 


Table 22-5 WPProgramFile Keys and Values 

WPProgramFile Keys 

Values Allowed 

ASSOCFILTER 

ASSOCTYPE 

Associated file extensions (such as *.TXT) 

Associated file types (such as Plain Text) 


You may have noticed that we applied WPObject keys to our WPProgram and 
WPFolder creations. In particular, 

if \SysCreateObject("WPFolder", "0S2 Warp Programming",, 

"<WP_DESKTOP>", "OBJECTID=<0WP4D_Folder>"), 
then say "Folder create failed." 

OBJECTID isn’t listed under WPFolder as a key name. What gives? 

All Workplace Shell classes have WPObject’s keys and values in common. 

The reasons for this will become apparent in the next part of this book. 


Setting Object Data 

You can change an object after creating it by using the same key and value 
combinations listed in the last section. The call is SysSetObject data. This call 
changes the icon file for the HELLO program object created earlier: 
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if \SysSetObjectData("<0WPDR_Hel1o>", 

" ICONFILE=C:\S0URCE\D0TNLINE.ICO"), 
then say "SetObjectData failed." 


Saving and destroying Objects 

Workplace Shell objects are, for the most part, persistent, meaning that once 
you create them you don’t need to do anything special to keep them on the 
Desktop. 

However, should OS/2 be shut down—should the power be interrupted or 
the computer get hung up by a program, forcing the user to reboot—changes 
made to the Desktop are not saved. (You may have experienced this phe¬ 
nomenon.) 

To explicitly save changes made to an object, you can call SysSaveObject: 


if \SysSaveObject("<0WPDR_Hel1o>", 1), 
then say "Object save failed." 



Now, even if the computer does shut down abnormally, the object will be 
saved. (The second parameter may be either 0 or 1, but the effect is essen¬ 
tially the same.) 

Saving a folder saves all of its contents, too. 

After creating an object, you can destroy it using SysDestroyObject: 


if \SysDestroyObject("<0WP4D_Folder>"), 
then say "Folder destroy failed." 



Destroying a folder destroys all of its contents, too. 

WPS will not prompt for verification when an object is destroyed by SysDe¬ 
stroyObject, even when the object is a folder. 


WPS User Functions 

You can duplicate user actions such as copying objects, creating shadows, or 
moving objects with the SysCopyObject, SysCreateShadow, and SysMoveOb- 
ject calls: 
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if \SysCopyObject("C:\0S2\IC0NEDIT.EXE", "<0WP4D_Folder>"), 
then say "Icon Edit Copy failed." 

if \SysCreateShadow("C:\", "<0WP4D_Folder>"), 
then say "C drive shadow failed." 

if \SysMoveObject("<0WP4D_Folder>", "<WP_0S2SYS>"), 
then say "Move failed." 

This code takes the folder created in the previous steps and puts a copy of 
the ICONEDIT.EXE program and a shadow of the C drive in it. It then moves 
the folder to the OS/2 System folder. 


Installing an Object on the Launch Pad 

The last thing we’re going to look at in this chapter is how to install an object 
on the LaunchPad. 

First of all, we know that to do anything with an existing object, we must have 
the object’s ID, or at least the object’s physical name. We don’t know what 
the LaunchPad’s ID is—is there any way we can find out what its physical 
name is? 

If you want to find out what an object’s physical name is, open a Details view 
of your Desktop: Click mouse button 2 on the Desktop, then click on the right 
arrow that appears next to Open. Another menu appears. Select Details from 
this menu. 

The Details view of the Desktop is split into two panes. The left pane holds 
mini icons for the object, the title, and if you scroll it, the object class. The 
right pane contains all manner of information, such as when the object was 
last written. 

The first column in the right pane is Real Name. You can use this to find out 
the physical name of the object on the disk. (If you’re using HPFS, by the way, 
the real name and the title will be the same, or very similar in many cases.) 

If you skim down this list, you’ll observe that some objects don’t have real 
names, and the LaunchPad is one of them. This is important: Some objects 
don’t exist anywhere except on the Desktop—that is, there is no physical file 
for the object. 

So, in this case, we guess. That’s how I figured out the LaunchPad’s ID—I just 
took a guess that it might be <WP_LAUNCHPAD>. There’s no easy way to get 
an object ID, and IDs are not always documented. 



332 


Part IV Polish and Panache 


Fortunately, the LaunchPad ID is <WP_LAUNCHPAD>. The LaunchPad class 
adds one key/value set called FPOBJECTS. The following code will put 
HELLO.EXE on the LaunchPad: 

if \SysSetObjectData("<WP_LAUNCHPAD>",, 

"FPOBJECTS=C:\SOURCE\HELLO.EXE"), 
then say "LaunchPad Install failed." 


Conclusion 

I hope this chapter was a pleasant diversion from the usual message process¬ 
ing, compiling, and linking that we’ve been doing throughout the rest of the 
book. 

This concludes our regular broadcast day. What follows in the next part 
should be both fascinating and, maybe, a wildly different approach to pro¬ 
gramming (for any environment) than you’re used to. 

Fasten your seatbelts. It’s going to be a bumpy night! 



oh -yeah, Windows'95 Is really -takii# off.' 











In This Part .. 


Am genuine WPS program adds objects to the Desktop 
W ® and allows users to interact with those objects in 
the same manner that they interact with all the standard 
OS/2 objects such as files and folders. In this way, the 
user is free to concentrate on the product of the pro¬ 
gram, not the program itself. 


You may be wondering, “If that’s a genuine WPS program, 
what’s a fake WPS program?” A WPS program can be 
somewhat faked by adding notebooks and containers to a 
non-WPS program, and by enabling its drag-and-drop fea¬ 
tures to communicate with Workplace Shell objects. 


Of course, WPS features are far easier to implement in a 
WPS program than in a regular PM program, because 
WPS takes care of many of the details. Implementing 
drag-and-drop in a non-WPS program requires the pro¬ 
grammer to take several sometimes complex steps to 
make everything work. 


Programming WPS does require a shift from the way 
we’ve been viewing Warp programming, however, and 
Chapter 23 is designed to help you make that transition, 
so no skipping! 



Chapter 23 


SOM: Kind of Wonderful? 

h this Chapter 

The crisis in software development 

The short course on object-oriented programming 

The System Object Model (SOM) 

Building a basic SOM class 



S oftware stinks. If you don’t believe me, think about all the times you’ve 
had a program crash (including the operating system or a device driver). 
Think about all the times you bought some software for a specific task, and it 
failed to perform that task. 


Look at the legal disclaimer on the inside of any software package, which 
always boils down to the same thing: “This program cannot be warrantied to 
perform any task under any circumstances, and we are not responsible for 
anything that happens to you should you assume that it can actually be used 
for some purpose.” 


Can you imagine buying a car without brakes? (“We’ll send you the brakes 
upgrade in the mail, along with some simple installation instructions.”) Or a 
house without a roof? (“We’ll put the roof on in the next release—this is only 
a version 1.0 house, after all.”) 

Now there, of course, is the rub. We aren’t making cars and houses here, 
which, by software standards, are relatively static and unchanging struc¬ 
tures. Innovations in the automotive and building industries happen over a 
period of many years. Innovations in the computer industry come and go 
rapidly within just a few years. 
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Nonetheless, the fact that software is expensive and time-consuming to pro¬ 
duce, and buggy when it finally is released, causes a great deal of concern. 
Some people do nothing else but study how to make software better. 

One of the more popular efforts in this area in recent years is a methodology 
(a way of programming, designing, and thinking) called object orientation 
(00). The 00 philosophy has been widely adopted by the industry (though 
there are still plenty of hold-outs) and its influence can be seen even in basi¬ 
cally function-oriented environments, such as the OS/2 or Windows operating 
systems, or the VX-REXX or Visual Basic development environments. 

Of course, software still comes out late and is probably more expensive and 
more bug-ridden than ever. Not to mention bigger and slower. To paraphrase 
Shakespeare: Our faults lie not in our methodologies, but in ourselves. 

I’ve been told that people can and do write hundreds of thousands of lines of 
code with few or no bugs in it. And they do so by adhering strictly to a 
methodology—it almost doesn’t matter which one. But most of us are too 
lazy or unwilling to pay for sufficient up-front design time to ensure a well- 
thought out, well-designed, and well-written program. 

Worse, any program (no matter how bad) is often better than no program at 
all. A buggy program can sometimes beat a better program by getting on the 
market first. 

However, 00 does have much to offer, even if it doesn’t end the quest for 
bug-free software. This is especially true for OS/2 programming, where the 
Workplace Shell is completely object oriented, and as a result saves us 
tremendous amounts of work. 


Life Would Be a Bream 

About all I can assume is that you’ve heard of object-oriented programming 
(OOP). You may or may not know it or be comfortable with it. You may hate 
it. None of that is relevant—I’m not here to convert you. 

What I want is to give you a taste of how much easier life would be if the 
entire Presentation Manager API was coded in an object-oriented fashion. 
And then I’ll tell you some reasons why it isn’t. 

You remember WinCreateStdWindow, I’m sure. Well, what if, instead of hav¬ 
ing a nine-parameter function call, you could just code something like the fol¬ 
lowing to create a window: 



Chapter 23 SOM: Kind of Wonderful? 337 


hwnd = winStandardWindow.Create; /* fake code */ 

Sure would make learning PM easier, wouldn’t it? If you wanted to change 
some attributes of your window, you might write something like: 

hwnd.SetColor(cl Red); /* fake code */ 

Now, imagine that instead of using WinSetWindowPtr and WinQueryWindow- 
Ptr to set and retrieve window data, you simply created your own new win¬ 
dow type, which had data fields of its own? With the same window handle, 
you might code something like: 

hwnd.MyDataFieldl = 42; /* fakeroo */ 

hwnd.MyDatafield2 = 3.1416; /* phony */ 

The handle itself would be a self-contained record holding all the information 
needed to change it, and having the capability to invoke all the functions with 
the correct information. 



Oh, wouldn’t it be loverly? 

Class libraries make this kind of programming possible, almost completely 
obscuring the API from the programmer. 

The down side of this is that one doesn’t learn the OS/2 API. The up side is 
that code written for a class library is potentially portable between operating 
systems. 


Of course, straight PM programming isn’t like this. Why? Well, what language 
was I using in the three preceding shippers? You can use your imagination, 
but the answer is: It doesn’t matter. 


Object-oriented programming takes functions and data and wraps them into 
convenient little packages called objects. But the wrapping process is unique 
from language to language: C++ is different from Object Pascal which is differ¬ 
ent from Smalltalk. (Not only that, versions of C++ differ from one to the next, 
as do versions of Smalltalk and Pascal.) 

If OS/2 chose any one of those languages, it would alienate developers in all 
the other languages. 

This is where the System Object Model (SOM) comes in. SOM is a “language- 
neutral” way of describing objects so that any language can use them. SOM is 
not a programming language. You don’t actually code an object using SOM; 
you only describe it. 


Here’s how the process works: 
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1. You describe your object using the SOM Interface Definition Language 
(IDL). 

2. You use a SOM “compiler” which takes your IDL file and creates files 
that you can use in your preferred language. 

3. You code the object using your preferred language. 

4. You compile the object using your preferred compiler. 

5. You use the object in another program, called the client program. 



Why should 1 care? 


In and of itself, SOM may not sound very 
exciting. If you work with an 00 language 
already, this will seem like you're taking many 
extra steps to get something you already 
have. (If you don't work with an 00 language, 
you're probably not all that interested in 
objects anyway.) 

However, SOM does offer benefits beyond 
those that are conferred by a single 00 lan¬ 
guage. First, you can write an object in C or 
Pascal (or in any language) and have it be 


used by a COBOL or Smalltalk program (or by 
a program written in any other language). 

Second, SOM makes some very advanced 
and amazing things possible—things like cre¬ 
ating a program from objects on different 
computers. 

We aren't going to get into any of the 
advanced properties of SOM, here. The only 
reason we care about SOM is that it is our 
gateway to genuine WPS programs. 



Any object-oriented language could potentially provide Direct-To-SOM capa¬ 
bility. That would mean that you could write an object in your favorite OO 
language and have the compiler take care of all the details described in the 
next section. 


The Direct-To-Som approach has a number of advantages, if it is available to 
you. Currently, the Metaware C++ compiler is the only compiler I know of that 
provides Direct-To-SOM capabilities, with IBM working on providing that fea¬ 
ture in the next release of their C++ compiler. 

We’ll go through the process of creating a SOM object and program later, but 
first, a quick OO primer to guarantee that you and I share a basic understand¬ 
ing of OO terms. 
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Object-oriented programming: 
the Reader's Digest Version 

Object-oriented programming is away to design and code programs around 
data, as opposed to around actions. Instead of defining a bunch of passive 
data structures and then a bunch of functions that apply to those structures, 
data and the functions that act on it are combined in a single logical unit. 

This is called the class definition (and, in fact, what we call object -oriented 
should really be called c/ass-oriented). When a variable of a class is created, 
it is called an instance of the class. An instance of any class is properly called 
an object. 

A class consists of two basic kinds of features: data and functions. I’ll refer to 
the data features as fields and the function features as methods , and use the 
term features to mean either or both. 

Beyond this, 00 programming is defined by three major concepts. The big 
three of 00 programming are: 

I is* Encapsulation 
v* Inheritance 
s* Polymorphism 

Encapsulation 

A class is said to be encapsulated when its fields are not directly accessible 
by clients. Access can be granted only through methods, such as GetName () 
or SetName (). Encapsulation insulates client programs from changes made 
to the class. 

Instead, access is granted through methods, such as GetName() or 
SetNameQ. 


inheritance 

A class need not be created in a vacuum. It can be created as a descendant of 
another class. A descendant of a class inherits all the features of the parent 
class. So, if an Address class was descended from the Name class, the 
Address class would inherit both the Name field and the GetName and Set- 
Name methods. You could then assign it additional attributes of its own. 
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A class can have more than one parent—this is called multiple inheritance 
(MI). We will not be using MI in this book. 

A class’s ancestors are its parent (or parents), its parents’ parents, and so on. 


A descendant class can alter the behavior of any inherited methods, if 
desired. 


Polymorphism 

For our puposes, polymorphism means that an object of any class is compati¬ 
ble with any of its ancestors. That means that a client program could have an 
object of the Name class or an object of the Address class and, without know¬ 
ing what the specific class was, could use the GetName and SetName meth¬ 
ods to access the name. 

For WPS programming, the implications of polymorphism are best under¬ 
stood this way: When a user tells an object to “open,” the object responds 
differently depending on what it is. WPS only knows that it is an object and 
that it responds to the command to open—it has no idea what the objects are 
going to do when opened, and it doesn’t care. 

So we only need to know that if we want our object to behave differently from 
other objects, we simply need to change what it does in response to certain 
commands. 


And Non) for SOM-tbing Completely 
Different 



Let’s go through the five steps required to build a SOM program, and make 
some sense out of the theory presented in the previous sections. 

The examples used in this chapter use SOM 2.0. You cannot compile these 
programs without a 2.0-compatible SOM compiler and a C compiler capable 
of interacting with the SOM output. 


The first step is to describe the class using the SOM Interface Definition Lan¬ 
guage (IDL). An .IDL file description consists of two basic components: the 
interface section, which describes features that the client may access, and an 
implementation section, which describes features that are hidden from the 
client. 


The following is a file called SOM1.C, which describes a class called See: 
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#include <somobj.idl> 

interface See : SOMObject 

/* Basic class definition begins with an 

interface section and a comment explaining 
what the class does. 


void aMethodO; 

// A description of aMethod 
attribute string chorus; 

string get_copyright(); 

// A description of get_copyright(); 

//# Other methods follow 

#ifdef _SOMIDL_ 

implementation 
{ 

string copyright; 


#endif 
} ; 



Looks a lot like C, doesn’t it? Not surprisingly, the creators of SOM decided to 
use a popular format for IDL. 

The See class is descended from the SOMObject class, and so inherits all of 
its features. However, we don’t care what those features are unless we want 
to change them. 


This is the basic format of a SOM class: 


u* #include <ancestor.idl> 

Interface classname: classancestor 
v* An open curly brace 

v* Definitions of publicly available methods and attributes 

^ #ifdef _SOMIDL_ 

v* Implementation 

v* Another open curly brace 

v* Implementation details, including fields 

^ A close curly brace, #endif, and another close curly brace ending a 
definition 
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Every section (except for the initial include statement) may be repeated so 
that an .IDL file contains more than one class definition. 



Comments on comments 


Note that the .IDL file uses standard C com¬ 
ment style (which follows the slash-asterisk 
format, /* */), the C++ comment style (which 
is a double slash, //), and a variation on the 
C++ comment style (a double slash followed 
by the pound sign,//#). 


Comments placed in certain locations in the 
.IDLfile get passed through to the files gener¬ 
ated by the SOM compiler, as we'll see. The 
exception to this is the //# style of comment, 
which is ignored by the compiler. 


IDL data t$pe$ and attributes 

Although the IDL is very C-like, it has only a few data types: short, long, 
unsigned short and unsigned long (16- and 32-bit integers), and float and dou¬ 
ble (floating-point numbers). For characters it has char (for a character) and 
octet (for a byte value). 

These simple data types map directly to C and C++ data types, as well as to 
data types in most other languages. 

The SOM IDL also allows structures, unions, enumerated types, and arrays. 
One type of array that you will commonly use is, of course, the string type, 
shown in the previous .IDL for See. 

SOM structures, unions, and enumerated types correspond very closely to 
those types in the C language. 

Any field of a SOM class can be declared as either a field in and of itself (in 
the implementation section) or as an attribute. 

SOM enforces encapsulation by denying direct access to fields defined in the 
implementation section by clients of SOM classes. To give clients access to 
the copyright field in the See class, I had to add a get_copyright() method. 

You may also define a data field as an attribute. Defining a field as an attribute 
causes the SOM compiler to create _get_field() and _set_field() methods for 
the attribute. 
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So, for the See class, the SOM compiler automatically generates 
_get_chorus() and _set_chorus() methods. 

In general, then, it’s easier to declare fields as attributes and let the SOM 
compiler create the methods on its own. You might use a regular field, how¬ 
ever, if you wanted to create a read-only field. Clients of the See class will be 
able to read the copyright field, but not change it, for example. 


The Ties That Bind SOM 

Note that nothing in the .IDL describes how the See class actually works. It is 
the SOM compiler that takes the .IDL file containing the class definition and 
turns it into a format that the language compiler can use. 

The Warp Toolkit comes with a program called SC.EXE which is a SOM com¬ 
piler capable of turning an .IDL file into a header and implementation file for 
the C and C++ languages. 

Open a command line in the directory containing the SOM 1.IDL file and type: 

sc soml 

The compiler will emit several messages about methods not being in “release 
order.” Ignore these for now. I’ll explain what they are later on. 

This simple little command will generate (by default) an .C file, an .H file, and 
a .IH file. The .C file is for you to fill in the implementations of the methods 
you described in the .IDL file. 

If you installed the Warp Toolkit with all the defaults, you should be able to 
follow the instructions given in this chapter exactly. If not, you may have to 
make some adjustments. 

If OS/2 can’t find the SC.EXE program, make sure that the C:\TOOLKIT\ 
SOMXBIN directory is part of your PATH statement in CONFIG.SYS. 

The .H file is for clients of the class, and the .IH file is for us to use in the 
implementation of the class. Fortunately, we don’t have to care anything 
more about them. (And trying to figure one out is a good way to make your¬ 
self nauseated.) 
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In implementing a SOM class, all we have to care about is the .C file. Look at 
the .C file generated by the SC.EXE program from the SOM1.IDL file: 


/* 

* This file was generated by the SOM Compiler and Emitter 

* Framework. 

* Generated using: 

* SOM Emitter emitctm: 2.41 
*/ 


#ifndef S0M_Module_soml_Source 
#define S0M_Module_soml_Source 
#endif 

#define See_Class_Source 
^include "soml.ih" 


/* 

* A description of aMethod 
*/ 

S0M_Scope void SOMLINK aMethod(See *somSelf, Environment *ev) 

{ 

SeeData *somThis = SeeGetData(somSelf); 

SeeMethodDebugC"See","aMethod"); 


/* 

* A description of get_copyright(); 
*/ 


S0M_Scope string SOMLINK get_copyright(See *somSelf, Environment 
*ev) 

{ 

SeeData *somThis = SeeGetData(somSelf); 

SeeMethodDebugC"See","get_copyright"): 

/* Return statement to be customized: */ 
return; 


Okay, this isn’t too difficult. We have some comments, some compile defines, 
and an include that gives us access to the SOM1.IH file. 
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After that are frames for the methods described in the .IDL file, which we are 
now supposed to fill in. 

Note that the comments placed after the method’s definition in the .IDL file 
get passed through to the .C file by the SOM compiler. 

Almost all the methods begin with the same two parameters: somSelf and 
Environment. 

somSelf is a concession to the non-object-oriented nature of the C language. 
(These are the same concessions that would have to be made in COBOL, 
standard Pascal, or any other non-object-oriented language.) In order to 
determine what object the method is being called to affect, the C program 
calling the method must pass a pointer to the object as the first parameter: 

_aMethod(instance, somGetGlobalEnvironment()); 

C++ (or a similar object-oriented language) would be able to access the 
method in a more natural fashion, in accordance with the rules for the lan¬ 
guage: 

instance->aMethod(somGetGlobalEnvironment()); 

Note that the non-object version of the call has an underscore prepended to 
the method name. We’ll see why that is in a moment. 

First, though, it is important to fill in the methods so that they actually do 
something. Here’s a fragment from SOM1.C showing the implementation of 
the two methods: 



S0M_Scope void SOMLINK aMethod(See *somSelf, Environment *ev) 
{ 

SeeData *somThis = SeeGetData(somSelf); 

SeeMethodDebugC"See","aMethod"); 

printf("Some Enchanted Evening ,\n"); 
printf("You may meet a stranger...\n"); 


/* 

* A description of get_copyright(); 
*/ 


S0M_Scope string SOMLINK get_copyright(See *somSelf, Environment 


SeeData *somThis = SeeGetData(somSelf); 
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SeeMethodDebug("See","get_copyright"); 

/* Return statement to be customized: */ 
return _copyright; 



These implementations are simple enough. The aMethod function prints out 
the opening lines to the song, “Some Enchanted Evening.” 

This is obviously not a class for use with PM, since it uses the standard printf 
function to display stuff on a command line-type screen. 

The get_copyright does nothing but return the copyright field of the See 
class. (Fields, like methods, have an underscore prepended to their names by 
the SOM compiler.) 


SOM clients 

All that remains is for us to use the SOM class in a client program. Let s take a 
look at a sample program that might access the class: 

#i include "soml.h" 

int main() 

{ 

See *aSee; 

Environment *GE = somGetGlobalEnvironment(); 
aSee = SeeNewC); 

_set_chorus(a See, GE, "In the night\nExchanging\ 

glances\nStrangers in the night\nWhat were the\ 
chances?\n"); 

_aMethod(aSee, GE); 

_somFree(aSee); 
return (0); 

} 


This gives a good basic idea of how you might use a SOM class in a client pro¬ 
gram. Since so many calls require the Environment parameter, you might set 
that up first in its own variable, as I have done here. 

To create a new instance of a class, you call the 

<cl assname>New() 

function. To free up the memory used by the instance, you use 
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_somFree(instance); 


The format for method calls is almost always going to be: 

_methodname(instance, GlobalEnvironment); 

Notice that even though we didn’t implement a _set_chorus or _get_chorus 
method, the SOM compiler created those methods and implemented them. It 
does this with any field that is defined as an attribute. It also prepends an 

extra underscore to the name so both_set_chorus and_get_chorus have 

two underscores preceding them instead of just one. (We’ll get to the reason 
why momentarily, I promise!) 

To compile the USESOM1.C program, enter the following on the command 
line in the directory containing the USESOM1.C and SOM1.C files: 



icc usesoml.c soml.c somtk.lib 

Notice that “icc” is the IBM C/Set++ compiler, not the Watcom or Borland 
compilers. At the time of this writing, C/Set++ is the only compiler of the 
three that supports SOM 2.0. 


Once again, if you installed the Warp Toolkit with the defaults, you’ll have no 
problems compiling. If you don’t have \TOOLKIT\SOM\LIB in your LIBPATH 
statement (in CONFIG.SYS) you will need to add it. 


The program compiles without warning and produces the following output 
when USESOMl.EXE is executed from the command line: 


Some Enchanted Evening, 

You may meet a stranger... 

The deal With the underscores 

So, why the underscores? Why can’t we just say: 

aMethod(aSee, GE); 

Well, the _<method> form of calling a SOM class method is the short form of 
calling a method. It’s short for: 


<classname>_<methodname> 
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Without the short form, the two method calls in the program would have to 
have been coded like this: 

See_set_chorus(aSee, GE, "In the night\nExchanging\ 

glances\nStrangers in the night\nWhat were the\ 
chances?\n"); 

See_aMethod(aSee, GE); 

So the single underscore is just a reminder of the fact that you have omitted 
the class name. 

The SOM compiler automatically adds an extra underscore for methods that 
it generates. That way, if you wanted to define your own set_chorus and 
get_chorus methods, they would be distinguishable from the SOM compiler¬ 
generated methods. 

The long form of the calls—the one that includes the class name is impor¬ 
tant to know. Why? Well, what if you’re using two SOM classes in the same 
program, such as another class called Saw, which also has a method called 
aMethod. 

You can no longer code this: 

_aMethod(aSaw, GE); 

_aMethod(aSee, GE); 

because the compiler doesn’t know which _aMethod to call, aSaw s or aSee s! 

In fact, SOM is perfectly capable of resolving the differences between calls so 
that the client program need not even know the class type. All the client has 
to know is the function’s signature (in this case, somSelf followed by Environ¬ 
ment). 

We will not be doing such heady stuff in this book, however. 

SOM does not let you use the short form for a method in a program where 
there is any ambiguity about which method is to be called. 


Release order 

When you compiled the .IDL file using SC.EXE, you got warning messages that 
looked something like these: 

"soml.idl", line 9: warning: "aMethod" is not in releaseorder. 
"soml.idl", line 11: warning: "_get_chorus" is not in rel easeorder. 
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"soml.idl", line 11: warning: "_set_chorus" is not in releaseorder. 
"soml.idl", line 13: warning: "get_copyright" is not in releaseorder. 


One of the main goals behind SOM is that objects created using SOM should 
be changeable without breaking client code. 

“Big deal,” you may think. “That’s the goal of all object-oriented program¬ 
ming.” Well, true, but with SOM the idea is not to break client executables! 

In other words, while you can bind SOM classes directly into the main pro¬ 
gram, you can also create a dynamic link library (DLL) file that contains your 
SOM class. 



A DLL is a library of routines that any number of programs can access at the 
same time, and which is loaded into memory only when programs request its 
services. The entire OS/2 API is contained in several DLLs that we have been 
using without even knowing it. 


Because a DLL is not physically part of an .EXE file, it is possible to change a 
DLL without breaking programs that use the DLL. 


Of course, you remember all this from Chapter 20, right? 

Part of the key to allowing compiled client programs to uniformly access the 
SOM object within the DLL, even though the object’s DLL may have been 
changed, is by specifying the order in which the object’s functions are 
released. 


If the order isn’t specified, then SOM is free to arrange the functions in what¬ 
ever order it wishes, and that order may change from time to time. 

The upshot of all this is only that at the very beginning of the implementation 
section, you should use the IDL’s releaseorder directive to specify the order. 

//# Other methods follow 


#ifdef _SOMIDL_ 

implementation 


releaseorder: aMethod, _get_chorus, _set_chorus, 
get_copyright 

string copyright; 
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It doesn’t matter what the order is, only that the order remains constant from 
version to version of your SOM class. If you add new methods, they should 
always go onto the end of the release order list, so as not to break any exist¬ 
ing code. 


Updating the SOM Class 

It seems a shame that the aMethod method doesn’t print out the chorus and 
the copyright notice as well as the two lines it does print out. 

We can resolve this simply enough by changing the implementation of 
aMethod in SOM1.C: 

S0M_Scope void SOMLINK aMethod(See *somSelf, Environment *ev) 

{ 

SeeData *somThis = SeeGetData(somSelf); 

SeeMethodDebug("See" , "aMethod"); 

printfC'Some Enchanted Eveni ng ,\n"); 
printf("You may meet a stranger...\n"); 
printf(_chorus); 
printf(_copyright); 


We can then recompile USESOM1 .C as shown above and run it, and every¬ 
thing works out fine—except that there is no value in the copyright field and 
there’s no way to set it. 




Well, we specifically didn’t want the client to be able to set the copyright, but 
obviously it needs to be set somewhere. Not only that, the chorus should be 
set to some initial value, or else who knows what will happen if the user calls 
aMethod before setting chorus? 

Technically, the value in an un-set object field is undefined— it could be any¬ 
thing. In practice, under OS/2, fields seem to begin pretty consistently with 
some kind of null value. I wouldn’t count on this if I were you, though. 

We can take care of both problems by overriding the somDefaultlnit method 
that See inherits from SOMObject. 

SOMObject has over twenty methods that it passes down to all of its descen¬ 
dants, but no fields. That gives descendant objects minimal overhead. 

Overriding a method takes place in the implementation section of the .IDL 
file. In general, overriding takes the form of: 
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<methodname>: override; 

Initialization methods are treated specially by SOM, however, so it is impor¬ 
tant to note that a method is an initializer. This is done by adding init to a 
method. In general, that would require defining a method in the interface sec¬ 
tion, as usual: 

void <methodname>() ; 

And then specifying that the method is an initializer in the implementation 
section: 

<methodname>: init; 

Since we are overriding the inherited method, we don’t need to define any¬ 
thing in the interface section. We do need to indicate that we are overriding 
an initializer in the implementation section, however, as this fragment from 
SOM1.IDL shows: 

//# Methods overridden from parent follow here 
somDefaultlnit: override, init; 

Use SC.EXE to compile the new definition. Now, at last, there should be no 
error messages. The SOM compiler quietly emits the .C, .IH, and .H files. 

Check out SOM1.C again and observe that the SOM compiler changes none of 
your work. SC.EXE is smart enough to leave your code alone. (It is not smart 
enough, however, to know when you’ve removed a method, so the code for 
any methods you decided to delete from your class will remain in the .C file.) 

The only new method is somDefaultlnit. It sets up a number of variables and 
calls your ancestral somDefaultlnit method to make sure that all of your 
inherited fields and such are properly set up. 

None of that should concern us here however. The SOM compiler adds a 
comment telling us where to put our initialization code, and that is easy 
enough to do. (The last two lines of the following function are code that I 
added.) 

S0M_Scope void SOMLINK somDefaultlnit(See *somSelf, somlnitCtrl* 


SeeData *somThis; /* set in BeginInitializer */ 
somlnitCtrl globalCtrl; 
somBooleanVector myMask; 

SeeMethodDebug("See","somDefaultlnit") ; 

See_Beginlnitializer_somDefaultlnit; 
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See_Init_SOMObject_somDefaultlnit(somSel f, Ctrl ); 

/* 

* local See initialization code added by programmer 
*/ 

_chorus = ""; 

_copyright = "(C) 1942, Mixed-Up Melodies"; 


Now if you compile USESOM1.C as before and run it, you’ll get the following 
output: 

Some Enchanted Evening, 

You may meet a stranger... 

In the night 
Exchanging glances 
Strangers in the night 
What were the chances? 

(C) 1942, Mixed-Up Melodies 


S0il libraries 

For WPS programs, it’s almost always going to be the case that we want our 
SOM classes to reside in DLLs. Although I’ll go into the mechanics of this as it 
specifically relates to WPS in the next chapter, it would be helpful to look at 
how, generally, one can create a .DLL from a SOM object, and use that .DLL in 
a client program. 

Only one change needs to be made to the .IDL file. In the implementation sec¬ 
tion, you can specify the .DLL that the class is going to be part of, though this 
isn’t strictly necessary. 

The general format for this is: 

dl1 name = "fi 1 ename.dl 1 " 

Specifically, in SOM1.IDL, this would be: 

implementation 
{ 

releaseorder : aMethod, _get_chorus, _set_chorus, 
get_copyright, sing; 
dl1 name = "soml.dl1"; 


string copyright; 
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In order to create a .DLL, a C compiler must have a .DEF file that tells it which 
methods the .DLL is going to export. 

However, we don’t even need to create this ourselves, because SC.EXE will do 
it for us: 


sc -sdef soml 

After creating the .DEF file, we need to create the .DLL. The C compiler will do 
this for us if we specify that we aren’t building a stand-alone .EXE file (the 
/Ge- option in the IBM compiler). 

icc /Ge- soml.c soml.def somtk.lib 


We have one more step to make this a .DLL that clients can use easily. We 
need to create a .LIB file from it. This is done using the IMPLIB.EXE program, 
which you will find in your \TOOLKIT\BIN directory. 



imp]ib soml.dll soml.lib 

Or you could use “implib soml.def soml.lib.” 

Now, here’s the cool part of this whole exercise. USESOM1.C doesn’t need to 
be changed at all! It only needs to be recompiled, and instead of compiling 
the SOM1.C file with it, just indicate that it should use the SOM1.LIB file. 


icc usesoml.c soml.lib somtk.lib 


Voila! Our SOM application is now using the .DLL form, instead of being com¬ 
piled and bound directly with the SOM class’s implementation file. Prove to 
yourself that the output is the same by running USESOMl.EXE now. 

To experience the wonder of it all, do the following: 

I ts 0 Change the initialization of the copyright field in the somDefaultlnit 
method of SOM1.C to: 

.copyright = “(C) 194 3, Mixed-Up Melodies”; 
v 0 Compile SOM1.C as before: 

icc /Ge- soml.c soml.def somtk.lib 

v 0 Without recompiling it, run USESOMl.EXE and behold—the output has 
changed, specifically the copyright notice: 
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Some Enchanted Evening, 

You may meet a stranger... 

In the night 
Exchanging glances 
Strangers in the night 
What were the chances? 

(C) 1943, Mixed-Up Melodies 

You could make far more drastic changes than that, too, but it gives at least 
you SOM idea (sorry, that’s the last SOM pun for a while) of what you can do 
with a SOM class in a .DLL. 


Conclusion 

Many questions about SOM may have occurred to you while reading this 
chapter. SOM is, in fact, worthy of a book of its own. 

However, we’ve learned enough here to go forward and build our own WPS 
classes, which was the whole point of this chapter. 


And that’s what we’ll do next. 



Chapter 24 


The Workplace Shell: 
Object of Envy 


In This Chapter 

What is the Workplace Shell, really? 
Creating a basic WPS object 
The metaclass concept 
Resources and WPS objects 
Calling inherited methods 
Context menus 


H 


aving gained some knowledge of SOM, it’s now possible for us to under¬ 
stand and appreciate the wonder that is the Workplace Shell. 


The Workplace Shell is an object hierarchy (that is, a group of classes 
descended from a single class and designed to serve a specific purpose) that 
complies with the SOM protocol. 


The actual implementation of the WPS classes was done by calling the same 
old Win* calls we’ve looked at throughout the rest of this book. In fact, the 
Desktop and all the folders are windows of the WC_CONTAINER class, and all 
the settings notebooks are, naturally, windows of the WC_NOTEBOOK class. 



About now you should begin to see how object-orientation has influenced the 
design of even function-oriented OS/2. The various types of windows are 
called classes , and they share common behaviors and attributes, just as real 
00 classes do. 


You’ll notice that I covered neither of those classes in the controls part of this 
book. Originally, I did write those chapters, but discovered that explaining 
how to make them work in a traditional PM program, and explaining how to 
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implement built-in WPS features such as drag-and-drop, would have taken up 
at least one-quarter of this book. 

In other words, it is possible to get very WPS-like effects from a PM pro¬ 
gram—but it is a mountain of work relative to simply building a genuine WPS 
program. 

In this chapter we’ll discover exactly how easy it is to implement notebooks 
and drag-and-drop in a WPS application. 


From Square Two) 

Now, you aren’t going to throw out what you learned in previous chapters. 
Everything you’ve learned so far about PM applies to WPS programs. So you 
aren’t starting from square one. 

What we’ll do now is create a WPS object, experiment with it a little bit, and 
then discover exactly where our PM knowledge comes into play. 

What we’re going to do in this chapter and the next is make a pizza. Or rather 
write a WPS pizza-making program. 

Imagine that you are the proprietor of an extremely high-tech pizza parlor, 
and you have a series of assembly robots that make your pizzas for you. You 
tell the robots what kind of pizza to make by tearing off a pizza template and 
then tearing off topping templates that indicate what toppings to put on the 
pizza, and how much of each topping. 

In this chapter, we’ll concentrate on the toppings. 

If you’re thinking “This is cute, but no one would ever really write a program 
like this,” you’re wrong. Well, it is cute, but it’s also very realistic. 

The pizza idea sprang from a more serious program I designed to do demo¬ 
graphic research. What I’m calling “toppings” now was demographic informa¬ 
tion, such as age group and gender. The “pizza” was the query constructed 
from the various demographic elements. 

This style of programming and programs is the wave of the future, and you 
are in a position to catch it, if you dare. 
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you Want Anchovies on That) 

The basic object class we are going to build will be called Topping. We’ll have 
a TOPPING.IDL file from which we’ll create a TOPPING.DLL file. 

Before we give the class any functionality at all, though, it’s helpful to create 
a simple WPS object, just to know that it can be done. 

Any WPS class is likely to be descended from one of three other classes: 

WPAbstract, WPFileSystem, or WPTransient. An abstract object stores its 
information in the OS/2.INI file. A file system object has one or more files 
associated with it where its information is stored. A transient object is not 
stored. (A print job would be an example of a transient object.) 

A WP Abstract object would be an object with no “real name” showing in the 
Details view—like the LaunchPad. (This was discussed in Chapter 22.) 

Our Topping class will be a WP Abstract descendant. The following is about 
the smallest .IDL file possible for a WPS class. It defines no new features, but 
can help give us a framework on which to build. 

#ifndef topping_id1 
#define topping_idl 

#include "wpabs.idl" 

interface Topping : WPAbstract 



#ifdef _SOMIDL_ 

implementation 


//# Class Modifiers 
majorversion = 1; 
minorversion = 1; 

passthru C_ih_before = "//define INCL_WINWORKPLACE" 

"#include <os2.h>"; 


} ; 

#endif /* _SOMIDL_ */ 

} ; 

#endif /* topping_idl */ 
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The only two new features here are SOM features: the majorversion and 
minorversion modifiers, and the passthru. WPS requires that its classes are 
built with version numbers. The passthru guarantees that the WINWORK- 
PLACE features of OS.2 will be added to the .IH file. (The C_ih_before tells the 
SOM compiler where to put the define and include statements.) Later we’ll 
use a similar passthru to create an .H file. 

You’ll be learning more and more about SOM as necessary to increase your 
WPS knowledge. 

Note also the “#include “wpabs.idl”” statement. If you’re going to descend 
from an object, you must include its .IDL in your .IDL. (The IDLs for all the 
WPS classes are in \TOOLKIT\IDL.) 


Try out the Topping class right now. Figure 24-1 shows what happens. 

WPS provides a standard icon for the red circle object with FS in it. (I have 
no idea what FS stands for.) Note that the object can be interacted with just 
as any other WPS object can. It has a menu, a settings notebook, and it can be 
dragged and dropped. And you didn’t have to do anything to make that 
possible! 


Figure 24-1: 
The minimal 
Topping 
class. 
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Managing your efforts 


The WPS development process involves the 
following basic activities: 

u* Editing the IDL 

v* SOM-compiling the IDL 

is* Editing the C file 

v* Compiling and linking the C file 

v* Compiling and linking any resources used 

Registering the class, and creating a test 
on the Desktop 

When you get the rhythm down, you'll move 
easily through this sequence. (If you make a 
mistake in the IDL or C file, of course, that 
breaks the pattern.) 

To facilitate this process, you can use a make 
file or a REXX .CMD file (my preference). In 
any event, make sure you use the following 
options to compile your SOM classes: 

icc /Wpro /ss /Ge- class.c class.def 
somtk.1ib 

The /Wpro option we've should be used with 
all C programs, the /ss allows double-slash 
comments (important because the WPS IDL 
classes have these, and they will be flagged as 
errors if this option is not on), and, of course, 
the /Ge- option specifies DLLs as opposed to 
executables. 

You should also use the /Gm+ option, of 
course, if you're going to make your class 
multithreaded. 

As we explore WPS throughout these 
chapters, follow along testing your objects 
with a simple REXX file like this: 


/* Installing the Topping object */ 
call RxFuncAdd 'SysLoadFuncs', 

'RexxUtil', 'SysLoadFuncs' 
call SysLoadFuncs 

if SysRegisterObjectClass('Topping' , 
'C:\SOURCE\TOPPING.DLL') then 
say 'Your pizza is ready!' 
else say 'The oven is broken, signore!' 

if SysCreateObjectC'Toppi ng', 

'Anchovies', 

'<WP_DESKTOP>','OBJECTID=<Anchovies> 

') then 

say 'Anchovies on the desktop!' 
else say 'Hold the anchovies, signore!' 

De-register and destroy your objects when 
done so you can continue to work on them. 
(You can't update the class DLL if an instance 
of the class is being used.) 

/* Uninstalling the Topping object */ 

call RxFuncAdd "SysLoadFuncs", 

"RexxUtil", "SysLoadFuncs" 
call SysLoadFuncs 

If SysDestroyObjectC"<Anchovies>") then 
say "Topping gone." 
else say "Destroy failed." 

if SysDeRegisterObjectClass("Topping") 
then 

say "Topping Forgotten." 
else say "De-registration failed." 

From here on, I'll just be telling you to "try this 
object out" and leaving the rest to you! 
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We’re going to WPS-empower ourselves by learning, feature by feature, how 
to turn this generic object into a WPS application. 

Alas, before we can do anything, we need a little more information on a SOM 
concept known as metaclasses. 


The Metaclass Concept 

In a true object-oriented system, everything is an object. There are no 
disembodied functions floating around. The Workplace Shell is a true object- 
oriented system. So how, then, do objects like the Topping object get created? 

You may be thinking that you create the object when you call SysCreateOb- 
ject (or WinCreateObject). That call isn’t really what creates the object. The 
call requests that the object be created. This begs the question: Of whom or 
what is this request made? 

There is an object called SOMClass that is part of the SOM hierarchy. SOM- 
Class is an object that creates objects. Think of it as a kind of object factory. 

We could avoid talking about it for a while because, by default, every new 
class you define has SOMClass as its metaclass, and that’s often perfectly 
acceptable. 

The main purpose of a metaclass, however, is to provide information that is 
true for every instance of the class. For example, previously we got this FS 
icon for our Topping object. It would be nice to have an icon specific to our 
Topping class, wouldn’t it? 

And does it really make sense to have every single object have its own icon 
data? Shouldn’t there be some way for them all to access the information that 
is common between them? Of course—and that way is the metaclass. 

Let’s implement a metaclass for Topping to see how metaclasses can be used. 


Changing, the class icon 

The other reason to talk about metaclasses right now is that there’s 
absolutely no way we can avoid them any longer. A good deal of WPS is 
implemented using metaclasses. 

For example, as you know, every object on the Desktop is represented by an 
icon. Each object belongs to a specific class, and every class has a default 
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icon. Most have representative icons, like a picture of a folder or a picture of 
a disk drive. 

But when an object doesn’t specify a particular icon for its class, it uses its 
parent’s icon. Because we didn’t specify an icon for the Topping class, we 
can therefore assume that the default icon for the WPAbstract class is the FS 
icon. 

The default icon for a class is secondary to any icon specified for a particular 
object. So, even though our anchovies have the FS icon, we could always 
change the icon directly through its settings notebook. 

We could then change it back to FS by selecting Default on the General page 
where the icon for an object is selected. 

But how does WPS get the icon data in the first place? When an object is 
being placed on the Desktop, WPS asks its metaclass. The method called is 
wpclsQuerylconData. 

In order to change the icon for our class, we therefore need to create a meta¬ 
class that overrides wpclsQuerylconData. This is easy enough. 

The actual wpclsQuerylconData method generated by the SOM compiler con¬ 
tains one particularly important parameter that we have to access in order to 
change the class icon: plconlnfo. 

The ICONINFO structure has an fFormat field that may be set to ICON_FILE, 
ICONJRESOURCE, ICONJDATA, or ICON_CLEAR. ICONCLEAR tells WPS to 
use the default icon. ICON_DATA is for those who feel the need to type in the 
icon data in its binary form. (Let’s not even walk down that road.) 

If fFormat is set to ICONJFILE, plconlnfo’s pszFileName field should be set to 
the path of the icon file to be used. 

That’s the instant gratification method, and it isn’t used all that often 
because you have to ensure that the .ICO file is with the DLL, and you have to 
know where it’s going to be, and so on. 

A more common approach is to set fFormat to ICON_RESOURCE. In this case 
you need to put a handle to a resource module in plconlnfo’s hmod field, and 
a resource ID in its resid field. To do this, you must first have a module han¬ 
dle, which involves taking a number of additional steps. 

So why use the resource module approach? Well, assume that the module is 
the .DLL containing the WPS object. That means you never have to “look” for 
the resource module because it is wrapped up with the class itself. 
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More importantly, a WPS object has a lot of resources. Notably, a WPS object 
usually has one or more menus that become part of its pop-up menus and 
one or more dialogs that become part of its settings notebook. (More on this 
important stuff later.) 

So the first order of business would seem to be creating the metaclass and 
giving it a generic method to retrieve the resource module, and then using 
this method from wpclsQuerylconData to get the class default icon. 

Typically a metaclass is given the name M_<classname>, and it is usually 
defined immediately after the class in the .IDL file. Beyond that, defining the 
metaclass is really no different from defining any other class. Here is the defi¬ 
nition for Topping’s metaclass: 


interface M_Topping: M_WPAbstract 


HMODULE clsQueryModuleHandle(); 

#ifdef _SOMIDL_ 

implementation 
{ 

releaseorder : clsQueryModuleHandl e; 

//#Class Modifiers 

majorversion = 1; 
minorversion = 1; 

wpclsQuerylconData: override; 

}; 

#endi f /* _S0MIDL_ */ 

} ; 

#endif /* topping_idl */ 

The connection between Topping and M_Topping would be made in Top¬ 
ping’s class modifiers section: 

//# Cl ass Modifiers 
majorversion = 1; 
minorversion = 1; 
metaclass = M_Topping; 

Running the new .IDL through SC.EXE gives us two new methods to fill in. 
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Retrieving the resource module involves: 

1 v* Getting a SOM ID for our class 
v* Locating the file that the class was loaded from 
u* Getting a resource handle using DosQueryModuleHandle 
v* Calling SOMFree when we’re done with the SOM ID 

The following method shows these steps in practice (the header and the first 
two lines of the method are generated by SC.EXE): 

S0M_Scope HMODULE SOMLINK clsQueryModuleHandle(M_Topping *somSelf, 

Environment *ev) 

{ 

PSZ path; 

somld id; 

/* M_ToppingData *somThis = M_ToppingGetData(somSel f); */ 
M_ToppingMethodDebug("M_Topping","cl sQueryModul eHandl e"); 


if (hmod == NULLHANDLE) { 

id = SOM_IdFromString("Toppi ng"); 

path = _somLocateClassFi1e( S0MC1assMgrObject, id , 

Topping_MajorVersion, Topping_MinorVersion); 
DosQueryModul eHandl e( path, &hmod); 

SOMFreeC (V0ID*)id); 

} 


return(hmod); 




} 

This is one of those situations where a static variable is okay. You can make 
hmod a static global variable here without worrying about side effects. 

SOMJdFromString returns an ID to the class with the name passed. This ID 
can be used in a number of ways, including the way shown here—using the 
SOMClassMgrObject’s _somLocateClassFile method to find the path of the 
.DLL containing the Topping object. 

The key to not getting overwhelmed by this is to explore the SOM and WPS 
the way you explored PM—by looking only for what you need and not trying 
to absorb everything at once. 


Now that we have a path, we can go back to the comfort of basic OS/2 calls 
for a moment with DosQueryModuleHandle. This function takes a path and 
provides a module handle, returning any error that might occur. 
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Make sure to add “#define INCL_DOS” before your “include <os2.h>“ direc- 
tive, or the program won’t work! 

Any SOM ID retrieved should be freed as shown with SOMFree when you are 
done with it. 


Now all that remains is to fill in the ICONINFO structure in wpclsQuerylcon- 
Data, and voila! A new class icon for Topping. (The complete listing appears 
on page 370.) 


Object Menus: Keeping Things in 
ConteKt 


A WPS object inherits a context menu from its ancestors, as you can see by 
clicking the mouse button on an installed Topping object. 

There are two basic things that you might want to do with an inherited con¬ 
text menu: 

Remove an item or submenu. 
v* Add an item or submenu. 


WPS menus work in this fashion: When the user creates a WM_CONTEXT- 
MENU event, the wpModifyPopupMenu method is called. The wpModify- 
PopupMenu method contains logic to insert menus into the context menu, 
but before doing so it creates a list of menu items it is going to add and calls 
wpFilterPopupMenu. 

The wpFilterPopupMenu eliminates any items it does not want in the context 
menu and returns the modified list to wpModifyPopupMenu. wpModifyPop¬ 
upMenu then calls wpInsertPopupMenuItems to actually insert the items. 

The “list” created by the modify method and passed to the filter method is 
actually a 32-bit LONG, where each bit represents an item that may be 
inserted. The standard items are given the following defines: 


CTXT_ARRANGE 
CTXT_CREATEANOTHER 
CTXT_FIND 
CTXT_LINK 
CTXT_NEW 
CTXT_PRINT 
CTXT_SELECT 
CTXT_SHUTD0WN 
CTXT_TREE 


CTXT_CL0SE 

CTXT_DELETE 

CTXT_HELP 

CTXT_L0CKUP 

CTXT_0PEN 

CTXT_PR0GRAM 

CTXT_SETTINGS 

CTXT_S0RT 

CTXTJaIINDOW 


CTXT_C0PY 
CTXT_DETAILS 
CTXT_IC0N 
CTXT_M0V E 
CTXT_PALETTE 
CTXT_REFRESH 
CTXT_SHAD0W 
CTXT_SWITCHT0 
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Not all of these items apply to all objects, of course. 

Eliminating a menu item becomes a very simple task, once you get the con¬ 
cept down. You simply override wpFilterPopupMenu, take whatever your 
parent would have returned (since it, too, might eliminate items), and elimi¬ 
nate the unwanted items. 

Figure 24-2 shows how WPS builds context menus. Here’s a sample of how we 
might eliminate the shadowing option from the Topping class: 

S0M_Scope ULONG SOMLINK wpFi1terPopupMenu(Topping *somSelf, 

ULONG ulFlags, HWND hwndCnr, 

BOOL fMultiSelect) 

{ 

/* ToppingData *somThis = ToppingGetData(somSelf); */ 

ToppingMethodDebug("Topping","wpFi 1 terPopupMenu") ; 


return 

} 


((Topping_parent_WPAbstract_wpFi 1 terPopupMenu (somSelf, 
1 Flags, hwndCnr, fMultiSelect) & ~CTXT_SHADOW); 


Figure 24-2: 
How WPS 
builds 
context 
menus. 


Custom 

Item List Item List 


( \ ( 

wpFilterPopupMenu wpModifyPopupMenu 


wpCustomFilterPopupMenu 


Override this 
to eliminate 
standard 
menu items. 


V ) 

Modified 

List 


L ) \ 

Modified 

List Create this 

so children 
can eliminate 
custom items. 


Respecting your parents 


Just because you are modifying your inher¬ 
ited behavior does not necessarily mean that 
you want to completely eliminate it, as the 
preceding code snippet shows. 

That's why SOM allows you to call any of your 


parent's methods from any of your methods 
merely by prepending parent_to the method 
name. 

Some methods are like teenagers, of course, 
and completely ignore their parents. 
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Adding Menu Items 

You could add menu items to your WPS object as easily as overriding 
wpModifyPopupMenu and adding a line of code like so: 

_wpInsertPopupMenuItems( somSelf, hwndMenu, 0, 
hmod, ID_OPENMENU, WPMENUID_0PEN); 

The menu items being inserted here (ID_OPENMENU and WPMENUID_OPEN) 
would have been retrieved from a resource file. 

And this is actually an okay thing to do—as long as you aren’t planning to 
have any children. If someone descends from your class and decides they 
don’t like your menu items, what can they do? 

Nothing, because you haven’t made modifications possible. In order to add 
menu items without forcing them on future generations, you must define 
your own context items and add a filter method to your object class, as Fig¬ 
ure 24-2 illustrates. 

So, before actually inserting your new menu items into the context menu, 
you set up your own CTXT_* items in your own bit mask, and call a new filter 
method that returns the bit mask intact. 

Future generations can eliminate the standard menu items in the usual way. If 
they want to eliminate the new Topping items, they override wpTopFilterPop- 
upMenu. 


A Practical Pizza Example 

To try all this out, we’ll expand the Toppings class in the following manner: 

is* Remove the shadow menu item. 
is* Add an “expired” menu item. 
is* Add a “quality” submenu. 

is* Make the “expired” menu item display a message. 

Let’s start with the IDL file for Topping. Segments of this that haven’t 
changed have been omitted to conserve space. 

#ifndef topping_idl 
^define topping_idl 
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#include "wpabs . id1" 

interface M_Topping; 

interface Topping : WPAbstract 
{ 


ULONG wpTopFi1 terPopupMenu(in ULONG ulFlags, 

in HWND hwndCnr, 
in BOOL fMultiSelect) ; 


#ifdef _SOM ID L_ 

implementation 

{ 

releaseorder : wpTopFi1terPopupMenu; 

//# Class Modifiers 
majorversion = 1; 
minorversion = 1; 
metaclass = M_Topping; 


passthru C_ih_before = 
"#define INCL_WINWORKPLACE" 
"//include <os2.h>" 


"#define 

TOPICON 

1" 

passthru 

C_h = 


"#define 

MID_E XPIREDMENU 

(WPMENUID_USER+1)" 

"#def i ne 

MID_QUALITYMENU 

(WPMENUID_USER+2)" 

"#define 

CMD_EX PI RED 

(WPMENUID_USER+3)" 

"#define 

MID_QUA LITY 

(WPMENUID_USER+4)" 

"#define 

CMD_GRADEA 

(WPMENUID_USER+5)" 

"#define 

CMD_GRADEB 

(WPMENUID_USER+6)" 

"#define 

CMD_GRADEC 

(WPMENUID_U S E R+7)" 

"#define 

CMD_GRADED 

(WPMENUID_USER+8)" 

"#def i ne 

CTXT_EXPIRED 

0x0001” 

"#define 

CTXT_QUALITY 

0x0002" 

"#defi ne 

CTXT_GRADEA 

0x0004" 

"#def i ne 

CTXT_GRADEB 

0x0008" 

"#def i ne 

CTXT_GRADEC 

0x0010" 

"#def i ne 

CTXT_GRADED 

0x0020" 


wpFi1terPopupMenu : override; 







368 Part V Workplace Shell Basses 


wpModifyPopupMenu : override; 
wpMenuItemSelected: override; 
1 ; 

//endif /* _SOMIDL_ */ 


interface M_Topping: M_WPAbstract 


HHODULE clsQueryModuleHandle(); 

#ifdef _SOMIDL_ 

implementation 
{ 

releaseorder : clsQueryModuleHandle; 
////Class Modifiers 


majorversion = 1; 
minorversion = 1; 


wpclsQueryIconData: override; 

}; 

#endif /* _SOMIDL_ */ 


#endif /* toppin g_id1 */ 



The only new and interesting stuff here is how I came up with the wpTopFil- 
terPopupMenu declaration. I stole it from the definition for wpFilterPopup- 
Menu. I could have made it a call with no parameters that returned a ULONG 
just as easily, but instead I decided to make it match wpFilterPopupmenu. 

The other interesting thing about the call is the in that appears before each 
parameter. Every parameter in a SOM method must be designated as an in, 
an out, or an inout parameter. 


From the function’s perspective, an in parameter is read-only, an out parame¬ 
ter is write-only, and an inout parameter is read/write. 


Here’s the .RC file for Topping: 


//include <os2.h> 
//include "topping, ih" 
//include "topping, h" 


ICON 


TOPICON 


TOPICO.ICO 
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MENU MID_EXPIREDMENU 

BEGIN 

MENU ITEM "-Expired", CMD_EXPIRED 
END 


MENU MID_QUALITYMENU 
BEGIN 

SUBMENU "-Quality", MID_QUALITY 
BEGIN 
END 
END 

MENU MID_GRADEAMENU 
BEGIN 

MENU ITEM "Grade -A", CMD_GRADEA,, 

END 

MENU MID_GRADEBMENU 
BEGIN 

MENU ITEM "Grade -B", CMD_GRADEB,, 

END 

MENU MID_GRADECMENU 
BEGIN 

MENU ITEM "Grade ~C", CMD_GRADEC,, 

END 

MENU MID_GRADEDMENU 
BEGIN 

MENU ITEM "Grade -D, but edible",CMD_GRADED,, 

END 

It’s pretty much like the others we’ve done, except that there are a number of 
multiple menus. Note that they are not packaged into a single submenu. 

As you’ll see with the .C file on page 370, a WPS submenu is built by creating 
the menu and adding one item at a time to it. This way, should a descendant 
of Topping decide that “Grade ~D, but edible” is not an acceptable quality 
level, that option can be removed in wpTopFilterPopupMenu with the addi¬ 
tion of ~CTXT_GRADED. 

The .C file follows. Pay particular attention to the wpMenuItemSelected 
method. This is where you will be notified when the user selects one of your 
menu items. You can handle the item request there, or you can invoke 
another method. 
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The standard menu items invoke their own methods, so that a click on the 
Copy menu item results in a call to wpCopyObject, a click on the Delete menu 
item results in a call to wpDelete, and so forth. 


/* 

* This file was generated by the SOM Compiler and Emitter 

* Framework. 

* Generated using: 

* SOM Emitter emitctm: 2.41 
*/ 


//ifndef S0M_Module_topping_Source 
//def i ne S0M_Modul e__toppi ng_Source 
//endif 

//define Topping_Class_Source 
//def ine M_Topping_Class_Source 

#define IN C L_WIN 
//include <os2.h> 

//include "topping.ih" 

//include "topping.h" 


HMODULE hmod = NULLHANDLE; 

S0M_Scope ULONG SOMLINK wpTopFi1terPopupMenu(Topping *somSelf, 

Environment *ev, ULONG ulFlags, 
HWND hwndCnr, BOOL fMultiSelect) 

{ 

/* ToppingData *somThis = ToppingGetData(somSelf); */ 

Toppi ngMethodDebug("Topping","wpTopFi1terPopupMenu"); 

/* Return statement to be customized: */ 
return (ulFIags); 

} 


S0M_Scope ULONG SOMLINK wpFi1terPopupMenu(Topping *somSelf, 

ULONG u1 FIags, HWND hwndCnr, 
BOOL fMultiSelect) 

{ 

/* ToppingData *somThis = ToppingGetData(somSelf); */ 
ToppingMethodDebug("Topping","wpFi1terPopupMenu"); 
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return (Topping_parent_WPAbstract_wpFilterPopupMenu(somSelf, 

ulFIags , 
hwndCnr, 
fMultiSelect) 


& ~CTXT_SHADOW) ; 


S0M_Scope BOOL SOMLINK wpModifyPopupMenu(Topping *somSelf, HWND 
hwndMenu, 


HWND hwndCnr, ULONG iPosition) 


ULONG flags; 

/* ToppingData *somThis = ToppingGetData(somSelf); */ 

ToppingMethodDebug("Topping","wpModifyPopupMenu"); 

flags=_wpTopFi1terPopupMenu(somSelf, somGetGlobalEnvironment(), 

CTXT_EXPI RED | CTXT_QUALITY | CTXT_GRADEA | 

CTXT_GRADEB | CTXT_GRADEC | CTXT_GRADED, 
hwndMenu, TRUE); 

if (flags & CTXT_EXPIRED) 

_wpInsertPopupMenuItems(somSelf, hwndMenu, iPosition, hmod, 

MID_EXPIREDMENU, WPMENUID_PRIMARY); 


if (flags & CTXT_QUALITY) 

_wpInsertPopupMenuIterns(somSelf, hwndMenu, iPosition, hmod, 

MID_QUALITYMENU, WPMENUID_P RI MARY); 

return (Topping_parent_WPAbstract_wpModifyPopupMenu(somSelf, 

hwndMenu, hwndCnr, iPosition)); 


S0M_Scope BOOL SOMLINK wpMenuItemSelected(Topping *somSelf, 

HWND hwndFrame, ULONG ulMenuId) 


ULONG newstatus; 

/* ToppingData *somThis = ToppingGetData(somSelf); */ 
ToppingMethodDebug!"Topping","wpMenuItemSelected"); 

switch(ulMenuld) { 
case CMD_EXPI RED: 

WinMessageBox(HWND_DESKTOP, HWND_DESKTOP, 

"The topping has expired!", "Mama Mia!", 

0, MB_CANCEL | MB_ERR0R); 
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return TRUE; 


return 

} 


(Topping_parent_WPAbstract_wpMenuItemSelected(somSelf, 

hwndFrame, ulMenuld)); 


S0M_Scope HMODULE SOMLINK clsQueryModuleHandle(M_Topping *somSelf, 

Environment *ev) 

{ 

PSZ path; 

somld id; 

/* M_ToppingData *somThis = M_ToppingGetData(somSelf); */ 
M_ToppingMethodDebug("M_Topping","cl sQueryModul eHandl e"); 


if (hmod == NULLHANDLE) 

{ 

id = SOM_IdFromString("Topping"); 

path = _somLocateClassFi1e( S0MC1assMgrObject, id , 

Topping_MajorVersion, Topping_MinorVersion); 
DosQueryModuleHandle( path, &hmod); 

S0MFree( (V0ID*)id); 

} 


return(hmod); 

} 


S0M_Scope ULONG SOMLINK wpclsQueryIconData(M_Topping *somSelf, 

PICONINFO plconlnfo) 

{ 

/* M_ToppingData *somThis = M_ToppingGetData(somSelf); */ 
M_ToppingMethodDebug("M_Topping","wpclsQueryIconData"); 


if (plconlnfo) 

{ 

pIconInfo->fFormat = IC0N_RES0URCE; 
pIconInfo->hmod= _clsQueryModul eHandl e(somSel f, 
somGetGlobalEnvironment()); 
pIconInfo->resid= TOPICON; 

} 


return (sizeof(ICONINFO)); 
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Conclusion 

We’ve covered a lot here in a short time. Even though it may seem that we 
haven’t been very productive, we have, in fact, unlocked the keys to WPS pro¬ 
gramming. 

All WPS programming is done in this manner: Override existing methods and 
add new methods. Although it may seem more complex because there are 
many different places to do things (as opposed to one big ClientWndProc), 
this kind of isolation between parts can make OS/2 programming easier once 
you get the hang of it. 

Next up: settings notebook. 




Chapter 25 

Notebooks and States 


In This Chapter 

Understanding the settings notebook 

Removing pages 

Adding pages 

Modeless dialog handling 

Initializing object data 

Saving object data 


0 


ur Topping class, although more sophisticated than the plain WPAb¬ 
stract object we started with, is still pretty useless. 


But some WPS objects have no open view—only a settings notebook in which 
the user can provide information about the object. Typically the object is 
then used in conjunction with some other WPS object. 


That’s perfect for the Topping class. There’s nothing really to look at other 
than the class icon. But remember, the purpose of the program is to provide 
information to the pizza-making machines about the kind of pizza desired, 
and right now, all we have is a generic topping. 


What we need is a new page or two in the settings notebook so that the user 
can describe what makes the topping. Before adding these pages to the Top¬ 
ping class, however, we’ll remove an unnecessary page. 
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Understanding Settings Pages 

The following actions occur when a settings notebook is requested: 
v* wpAddSettingsPage is called. 

V s0 wpAddSettingsPage calls one or more other methods to add the other 
pages. 

These other methods call wpInsertSettingsPage to add their pages. 

The method names follow (roughly) the form : 

wpAdd<PageName><PageNumber>Page 

For example, the Desktop’s Lockup pages are added with the methods 
wpAddLockuplPage, wpAddLockup2Page, and wpAddLockup3Page. 

Sometimes the <PageName> part is made more specific than what is shown 
on the notebook tab. The method that adds the general page, for example, is 
wpAddObjectGeneralPage. 

Ultimately, however, this is a fairly simple system to work with: To add a page, 
you simply add a method that creates the page and calls wpInsertSettingsPage. 
Then you override wpAddSettingsPage to call the new method (or methods). 
To remove a page, you override the method that adds the page so that it 
does nothing but return SETTINGS_PAGE_REMOVED. 


Removing the Window Page 

The WpAbstract class assumes that an object is going to have a view of some 
kind, so it gives its descendants a Window settings page to determine what 
should happen if multiple windows on the same object are open, what should 
happen if the window is minimized, and so forth. 

Topping should remove this page, obviously, since it has no views. This is 
done by overriding AddObjectWindowPage. 

This following code is all created by SC.EXE when you put “AddObject¬ 
WindowPage: override” into Topping’s implementation. 

The only thing changed is the return statement, for which I have substituted 
SETTINGSJPAGEJREMOVED for the call to the parent method. 
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S0M_Scope ULONG SOMLINK wpAddObjectWindowPage(Topping *somSelf, 

HWND hwndNotebook) 

{ 

/* ToppingData *somThis = ToppingGetData(somSelf); */ 

ToppingMethodDebug("Topping","wpAddObjectWindowPage"); 

return (SETTINGS_PAGE_REMOVED); 

} 


Adding Window Pages 

Adding Window pages isn’t much more complex, except that it involves deal¬ 
ing with the PAGEINFO structure that describes notebook pages. (And if you 
think adding a settings notebook page is difficult, be grateful you didn’t have 
to build the notebook from scratch, as you would in a non-WPS program.) 

Table 25-1 shows a subject of PAGEINFO fields. In the interest of conserving 
space, some elements of the PAGEINFO structure are not included either 
because we can’t cover them in this book or because they’re not very useful. 
Start by filling your PAGEINFO structure with zeros to clear out the fields 
you’re not interested in. 

We’ll fill in the rest to create a new settings notebook section for toppings. 


Table 25=1 Selected PAGEINFO Fields 

Field Name 

Description 

cb 

sizeof (PAGEINFO) 

hwndPage 

NULLHANDLE 

pfnwp 

Window procedure 

resid 

Resource ID 

pCreateParms 

Creation parms (usually somSelf) 

dlgid 

Identifies the page 

usPageStyleFlags 

BKA_MAJ0R, BKA_MIN0R 

usPagelnsertFlags 

BKA_FIRST, BKA_LAST, BKA_NEXT, BKA_PREV 

usSettingsFlags 

SETTINGS_PAGE_NUMBERS 

pszName 

Page name 

ulPagelnsertld 

Notebook control page identity 
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Note that the pages you insert should have their own window procedures. In 
our case, we’ll write one window procedure to handle both pages. 

Here again, we can see the advantages of adding the clsQueryModuleHandle 
method to the metaclass. The resource file we have been using for icons and 
menus can now be used for settings pages. 

You’ll usually put somSelf in the pCreateParms field because the settings 
notebook is going to be taking the user data and changing the Topping 
object’s data according to what the user has entered in the various fields. 

The dlgid field allows us to distinguish between the two dialogs, if we so 
choose. 

We’ll use the page style options to give our new pages their own section. A 
notebook page that has BKA_MAJOR set will get a tab and be treated by the 
notebook as the first page of a section. Subsequent pages are considered part 
of that section until the next BKA_MAJOR option is set. BKA_MINOR tabs 
appear along the bottom and act as subsections within a major section. 

The page insertion flags determine where the page is going to appear in the 
notebook. If the SETTINGS_PAGE_NUMBERS flag is set, the pages will be num¬ 
bered, as in 1 of 2, 2 of 2, and so on, according to the number of pages in the 
section. The page name will appear on any tab associated with the page. 

Were we building a notebook in a non-WPS program, we would also have to 
specify hwndPage and ulPagelnsertld. The hwndPage would be a window we 
created specifically for the page, and the ulPagelnsertld would be a number 
returned when we sent the notebook a message that we wanted to insert a 
page. 

In a WPS program, we must override the wpAddSettingsPages method and 
from there call the other methods that add our own settings pages. These 
methods call wpInsertSettingsPages, which fortunately takes care of most of 
the ugly details. 


Step-By-Step Notebooks 

Here are the best steps to take when building a notebook, especially when 
first starting out (follow along with Topping now): 

1. Add “wpAddSettingsPages: override” to your class implementation. 

2. Add “ULONG wpAdd<Name><Number>Page(in HWND hwndNotebook);” 
to your class interface, as in 
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l.ULONG wpAddToppinglPage(in HWND hwndNotebook); 

3. Compile the IDL file. 

4. Use a dialog editor to build a prototype dialog for the page. Save the dia¬ 
log and its include file under a meaningful name. (In this case, I decided 
to go with Pagel.) Turn off the titlebar, system menu, and border 
options (Figure 25-1) so that the dialog makes a good notebook page. 

5. Edit your .RC file to include the dialog’s header file and the dialog itself: 

//include <os2.h> 

//include "topping, ih" 

//include "topping, h" 

//include "pagel.h" /* add this */ 

. . . /* menu definitions, etc., here */ 
rcinclude pagel.dig /* and this */ 

6. Your .C file will have an AddSettingsPages method, to which you will add 
statements to call your settings pages method. 


Figure 25-1: 
The 
Topping's 
new 
notebook 
page. 
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To keep the listings neat, I’m not showing the entire code lines that the SOM 
compiler generates, which are too long to print on single lines of the book. 
Any place you see ellipses (...), this is what 1 have done. These are only lines 
that remain unchanged, of course. 


S0M_Scope BOOL SOMLINK wpAddSettingsPages(Topping... 


_wpAddToppinglPage(somSelf, 
somGetGlobalEnvironment(), 
hwndNotebook); 


/* add */ 

/* this */ 

/* statement*/ 


return (Topping_parent_WP. 

} 


1. Your .C file will have method frameworks for your settings pages 
method, which you fill in: 

S0M_Scope ULONG SOMLINK wpAddToppinglPage(Topping... 

{ 

PAGEINFO pi; 

/* ToppingData *somThis = ToppingGetData(somSelf); */ 
ToppingMethodDebug("Topping","wpAddToppinglPage"); 

/* Return statement to be customized: */ 
memset((PCH)&pi,0,sizeof(PAGE INFO)); 


pi . cb 

= sizeof(PAGEINFO); 

pi.hwndPage 

= NULLHANDLE; 

pi.usPageStyle FIags 

= BKA_MAJ0R; 

pi.usPagelnsertFlags 

= BKA_FIRST; 

pi.pfnwp 

= WinDefDlgProc ; 

pi.resid 

= hmod; 

pi .dlgid 

= PAGE1; 

pi.pszName 

= "Topping"; 

pi .pCreateParams 

= somSelf; 

return __wpInsertSetti 

ngsPage( somSelf, hwndNotebook 


} 

2. Test the object by compiling and creating an object on the Desktop. If 
you want to make any changes, you uninstall the object. 

3. If you want to change the style or position of the page as it appears in 
the notebook, you do so by changing the C code and recompiling to 
check on the new status. 

4. If you want to change the dialog, use the dialog editor to change it, then 
recompile the resource and bind it back into the .DLL. (You don t need 
to recompile the C code.) 
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Try this with a blank page first, then add some controls to the dialog. We’re 
going to proceed from here with a single entry field control that will contain a 
description of the Topping. 


Modal Dialog Event Handlers 

The event handling procedure for the dialogs is pretty straightforward, too. 
We need to take some steps to allow the Undo capability that is usual for 
WPS objects. (There isn’t a good default setting for a pizza topping, so I 
skipped that button.) 

Although this is a WPS program, the steps here apply to most modeless dia¬ 
log handling: 

I v 0 Copy the data elements that the dialog can change. 

v 0 When the user changes the control focus, set the actual data (not the 
copy) to the new value in the control. 

v 0 When the user closes the dialog, nothing more needs to be done. 

^ If the user presses the Undo button, restore the copy. 

Here’s the code for the dialog’s event handler: 

MRESULT EXPENTRY ToppingDlgProc(HWND hwnd, ULONG msg, MPARAM mpl, 
MPARAM mp2) 

{ 

PTOPPINGDLGDATA td; 

MRESULT mr = FALSE; 

char string[100]; 


/*event handler*/ 
switch(msg) { 

case WM_INITDLG: 

td = mal1oc(sizeof(TOPPINGDLGDATA)); 

WinSetWindowPtr(hwnd, 0, td); 
td->so = mp2; 

strcpy(string, _get_description(td->so, td->env)); 
td->desc = mal1oc(strlen(string)+l); 

strcpy(td->desc, string); 

Wi nSetWindowText( 

WinWindowFromID(hwnd, EF_DESCRIPTION ), 

td->desc); 
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return 0; 
case WM_COMMAND: 

td = WinQueryWindowPtr(hwnd, 0); 
switch(SH0RT1FROMMP(mpl)) { 
case PB_UND0: 

WinSetWindowText( 

WinWindowFromID(hwnd, EF_DESCRIPTION), 

td->desc) ; 
return 0; 


break; 

case WM_DESTROY: 

td = WinQueryWindowPtr(hwnd, 0); 

WinQueryWindowText( 

WinWindowFroml D( hwnd , EF_DESCR IPTION ), 100, 
string); 

_set_description(td->so, td->env, string); 
return 0; 

default: 

mr = WinDefDlgProc(hwnd, msg, mpl, mp2); 
break; 

} 


return mr; 
} 


For a page of a window dialog, you generally want to return FALSE in its event 
handler procedure. Otherwise, the user could press Esc and have just that 
page of the dialog go away! (This is true of any notebook in OS/2, not just 
WPS.) 

Also, note that in a real WPS notebook dialog, you’d respond to every 
WM_CHANGEFOCUS command. Any time the user changes focus, you want to 
update the field represented by the control that is losing the focus. 

So if the user has typed something into “description,” and then moves to 
“calories per serving” (not shown in this code), you would update the 
description field. 

And you copy all of the structure’s fields, so that if the user presses Undo, 
you can feed them back into the original structure. 

PTOPPINGDLGDATA is one of our usual window data structures, used for the 
same reasons. There are, however, variations on how you might define and 
access this structure: 
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| u* You can declare the structure at the beginning of the .C file. (Do this 
when the structure is specific to a particular client.) 

v 0 You can create a separate .H file, other than the one created by SC.EXE. 
This creates an extra file for you to distribute along with your object 
.DLL. 

You can use the passthru capability of SOM to imbed a structure defini¬ 
tion in the .IDL file. 

We’re already following the second approach, because we’re including 
PAGE1.H from the dialog. This has some advantages, but the usual approach 
is to use passthru: 

passthru C_h_after = 

"typedef struct" 

" r 

" Topping *so;" 

Environment *env;" 

PSZ d e s c;" 

" } TOPPINGDLGDATA;" 

"typedef TOPPINGDLGDATA *PT0PPINGDLGDATA;" 


Notice that the file this is emitted to is the .H file, and after —well, after what? 
The SOM compiler puts all the definitions that the client programs are going 
to need in the .H file. By specifying “after,” your passthru text will come after 
the important type definitions—in this case Topping is particularly impor¬ 
tant, since it’s part of the definition. 

The defines we made earlier don’t depend on anything in the IDL, so they can 
use “passthru C_h_before” or “pass C_h”, which are the same. 


Initializing Object Bata 

In Chapter 23, we overrode the somlnit method to set up our instances data. 
WPS objects inherit the behavior that somlnit calls wpslnit and wpslnit sets 
all instance data to zero. 

wpInitData is where WPS objects initialize their data. However , this method is 
called not only when an object is first created but also when an object is 
restored—in other words, not just when the user tears off a new object, but 
every time the user boots WPS. 

wpInitData is followed by wpSetupOnce if the object is a new one, or by 
wpRestoreState if the object is being restored. 
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It is the metaclass that creates the object and calls the various initialization 
methods in its own wpclsNew method. 

You can override wpInitData to provide specific values for your class fields. 
You can also override the wpSetup method so that your object can add new 
key name fields to be used by WinCreateObject (or SysCreateObject, in REXX). 

We’re going to take the approach that we want to add a setup key name to 
our object class, so we’ll override wpSetup: 

S0M_Scope BOOL SOMLINK wpSetup(Topping *somSelf, 

PSZ pszSetupString) 

{ 

char value[100]; 

ULONG len = 100; 

ToppingData *somThis = ToppingGetData(somSel f); 

Toppi ngMethodDebug("Topping","wpSetup"); 

if (_wpScanSetupString(somSelf, 

pszSetupString,"description",value,&1en)) { 

_set_description(somSelf, somGetGlobal Environment(), value); 
} 



return 

} 


(Topping_parent_WPAbstract_wpSetup(somSelf, 
pszSetupString)); 


The wpScanSetup string parses the setup string for the “keyname=value;” 
pattern, thus easing the task of creating new key names for our object. Obvi¬ 
ously, were we setting a non-string field for our object, we’d have to convert 
the object to the appropriate type. 

The following REXX code creates a topping named Pineapple on the Desktop, 
and a description of Pineapple. (Topping must be registered first, of course.) 

SysCreateObject('Topping' , 'Pineapple', '<WP_DESKTOP>',, 

'OBJECTID=<Pineapple>;Description=Pineapple ; ' ) 

Saving and Restoring Object Data 

SOM objects and their data are not automatically saved. And even though 
any instance of Topping we create on the Desktop will remain there, the 
description field will not be saved unless we specifically save it. 



Chapter 25 Notebooks and States 385 



You can prove this to yourself by leaving a topping on the Desktop, and shut¬ 
ting down your system. Whatever the description field was (either Pepperoni 
or Pineapple) when you shut down, it will come back a NULL string. 


Saving object data is done in the object’s wpSaveState method, often through 
the use of the wpSaveLong and wpSaveString methods: 


S0M_Scope BOOL SOMLINK wpSaveState(Topping *somSelf) 


ToppingData *somThis = ToppingGetData(somSelf); 
ToppingMethodDebug("Topping","wpSaveState"); 


_wpSaveString(somSelf, "Topping", KEY_DESCRIPTION, 
_description); 


return (Topping_parent_WPAbstract_wpSaveState(somSel f)); 


The parameters are somSelf (as always), the class name, a long integer key, 
and the field being saved. This is for both wpSaveString and wpSaveLong. 
Only the type being passed changes. (You can place your KEY_* defines with 
your other defines in the .IDL file.) The data is saved to OS2.INI. 

Restoring object data is done in the object’s wpRestoreState method, 
through the wpRestoreLong and wpRestoreString methods: 

S0M_Scope BOOL SOMLINK wpRestoreState(Topping *somSelf, ULONG 

ulReserved) 


char string[100]; 

ULONG len = 100; 

ToppingData *somThis = ToppingGetData(somSelf); 

ToppingMethodDebug("Topping","wpRestoreState"); 

_wpRestoreString(somSelf, "Topping", KEY_DESCRIPTION, 
string, &len); 

_set_description(somSelf, somGetGlobalEnvironment(), string); 

return (Topping_parent_WPAbstract_wpRestoreState(somSel f, 

ulReserved)) ; 


The wpRestoreString method requires the same object, class name, KEY_* 
define, and then a place to put the variable. For a LONG, that can be the 
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actual object field. For a string, I use a local variable and then use the set 
method, so that the exact amount of string space can be allocated. Also for a 
string, an additional field (&len) indicating the size of the buffer is required. 


Conclusion 

Well, now we that have an object class, we have data that persists. As I said 
earlier, however, the usual point of an object like this is to interact with other 
objects. 


So, now that we have Toppings, it’s time to make a pizza. 



Chapter 26 

Containing Your Excitement 


In This Chapter 
The WpContainer class 
Drag-and-drop 
Your own views 
Integrating your PM knowledge 


u mne of the coolest things about WPS is its collection of direct manipula- 
tion features, and an important part of those features is the WC_CON- 
TAINER class. Implementing a container class in a non-WPS program can be a 
pretty big deal, particularly if you want to enable it with drag-and-drop func¬ 
tionality—and what’s the point otherwise? 


A WpContainer descendant inherits a lot of capabilities and so makes at least 
a simple implementation of a container easy. 


In fact, we’ll explore the container class the same way we explored the 
abstract class. We’ll start with the simplest implementation possible, see 
what it gets us, and find out how we can add to it. 


\/our Basic Cheese-and- Tomato 

The IDL for the PIZZA class should look familiar: 

//ifndef pizza_idl 
#define pizza_idl 

//include <wpf ol der. i dl > 

//include <somcls.idl> 


interface M_Pizza; 
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interface Pizza : WPFolder 


#ifdef _SOMIDL_ 

implementation { 

majorversion = 1; 
minorversion = 1; 
metaclass = M_Pizza; 

passthru C_ih_before = 
"#define INCL_WINWORKPLACE" 
"#include <os2.h>" 


#define PIZZAICON 100 


//# Method Modifiers 

}; 

#endif 
} ; 

interface M_Pizza: M_WPFolder 
{ 


#ifdef SOMIDL 

implementation { 

//# Class Modifiers 
majorversion = 1; 
minorversion = 1; 

//# Method Modifiers 
wpclsQueryTitle: override; 
wpclsQueryIconData: override; 
wpclsQueryStyle: override; 


}; 

#endif /* _SOMIDL_ */ 

} ; 

#endif /* pizza_idl */ 
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There are two new class methods shown here: wpclsQueryTitle and wpcls- 
QueryStyle. The wpclsQueryTitle method provides a default title for the 
object. If you create a Topping object on the Desktop, open its settings note¬ 
book to the General page, and press the Default button, the title of the object 
reverts to Abstract. (This characteristic is inherited from Topping’s parent, 
WP Abstract.) 

S0M_Scope PSZ SOMLINK wpclsQueryTitle(M_Pizza *somSelf) 

{ 

/* M_PizzaData *somThis = M_PizzaGetData(somSelf); */ 

M_PizzaMethodDebug("M_Pizza","wpclsQueryTitle"); 

return "Pizza Pie"; 

} 


Now, if you create an instance of Pizza on the Desktop with a Title of Deep 
Dish, and then push the Default button on the General page of the settings 
notebook, the title reverts to Pizza Pie. 

The wpclsQueryStyle determines how instances of a class may be used. You 
can return any combination of the styles in Table 26-1 to create various 
effects. 


Table 26-1 Workplace Shell Class Styles 


Style Description 

Instance can't become template 


CLSSTYLE_DONTTEM PLATE 

CLSSTYLE_NEVERCOPY 

CLSSTYLE_NEVERDELETE 

CLSSTYLE_NEVERDRAG 

CLSSTYLEJMEVERDROPON 

CLSSTYLE_NEVERLINK 

CLSSTYLEJMEVERMOVE 

CLSSTYLE_NEVERPRINT 

CLSSTYLE_NEVERRENAME 

CLSSTYLEJMEVERSETTINGS 

CLSSTYLE_NEVERTEM PLATE 

CLSSTYLEJMEVERVISIBLE 


Can't be copied 
Can't be deleted 
Can't be dragged 

Can't be target of drag (dropped on) 

Can't be shadowed 

Can't be moved 

Can't be printed 

Can't be renamed 

No settings notebook 

Class can't have template 

Instances can't be made visible 





390 FartV Workplace Shell Basics _ 

Note that DONTTEMPLATE and NEVERTEMPLATE are different. The first 
keeps the check box on the general page from being set. The second prevents 
a template from being created under any circumstances. 

That’s especially important here, because any class descended from 
WPDataFile will automatically create a template for itself when registered. 

A class is descended from its parent and its parent’s parents, and so forth, all 
the way down to SOMObject. So, while our class’s immediate parent is 
WPFolder, WPFolder’s parent is WPDataFile. (WPDataFile might be called the 
grandparent of the Pizza class.) 

(Topping was descended from WPAbstract, which doesn’t have this 
behavior.) 

Here’s an example using NEVERTEMPLATE: 

S0M_Scope ULONG SOMLINK wpcl sQueryStyle(M_Pizza *somSelf) 

{ 

/* M_PizzaData *somThis = M_PizzaGetData(somSel f); */ 

M_PizzaMethodDebug("M_Pizza","wpclsQueryStyle"); 

return(M_Pizza_parent_M_WPFolder_wpclsQueryStyle(somSelf)) 

| CLSSTYLE_NEVERTEMPLATE; /* no templates */ 


Strictly speaking, there’s nothing wrong with having a Pizza template, but the 
problem is that the template is created automatically, and you must delete it 
before you can delete the .DLL. (You can’t delete a .DLL if it is in use.) 

Every time you go to test the class, you have to delete not only the instance 
you created, but also the template, which can be a challenge. 


Who Dropped a Printer on the Pizza) 

Now that we have a container object for our pizza, we can put our toppings 
on it (or more accurately, in it). Unfortunately we can put anything else in 
there, too: a data file, a program, a printer, anything. 





The Black Hole 

An indispensable tool for WPS programming The Black Hole destroys any WPS object 
is the Black Hole. The Black Hole is a WPS dropped on it. Anything, 
object created by Gregory Czaja, one of the 

programmers of DeskMan/2 (an OS/2 Desk- The Black Hole is part of DeskMan/2 or can 
top manager). be found as freeware on many bulletin 

boards or on OS/2 shareware/freeware CDs. 


We need to make the Pizza object a bit more discriminating. This involves 
overriding two methods: 

//# Method Modifiers 

wpDragOver: override; 
wpDrop: override; 

The wpDragOver method is called when the user drags an object over 
another, and the wpDrop method is called when the user drops the object. 

If a non-Topping is being dragged over our pizza, then we want to make sure 
that WPS knows it’s not okay to drop. (WPS informs the user by drawing the 
“No” symbol.) If the object is dropped, we want to make sure that the user 
knows that the drop is not okay. 

Since we’re going to need to check the validity of the objects in two different 
methods, we should add a new method of our own called ValidateDragAnd- 
Drop: 

BOOL ValidateDragAndDrop(in PDRAGINFO pdrglnfo); 

The basic steps you follow to implement drag-and-drop in a non-Workplace 
Shell application are: 

v* Intercept the command to begin the drag. 
v* Create a DRAGINFO structure. 

v* Create one or more DRAGITEM structures to hold information about the 
object or objects being dragged. 

v* Prepare a DRAGIMAGE structure. 

v* Call an API function to start the drag. 
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I v* Change the cursor’s appearance to include DRAGIMAGE. 

v* Intercept and respond appropriately to the various messages generated 
by the user dragging the object. 

And that’s the short version, without going into detail about what the various 
drag messages are! 


In a Workplace Shell application, as you have seen, you need to do exactly 
none of this. Any WPS object can be dragged (unless the CLSSTYLEJMEVER- 
MOVE is set) and any WPFolder object can accept an object. 


Okay, that’s a bit of a fib, since you’ll usually customize the behavior of the 
folder so that it reacts meaningfully to the object being dragged over it or 
dropped on it. 



Actually, if you want the folder to merely display different kinds of informa¬ 
tion about objects than a regular WPS folder displays, you don't really need 
to do anything more than modify the container so that it displays different 
information than WPFolder does. 



Another important point is that you can modify these behaviors we’re talking 
about for any WPS object. For example, if we had a Salt Shaker object, we 
might want to allow the user to drop it on the Topping object, and that could 
be done easily, too. 


Let’s look at the two data structures that govern drag-and-drop before look¬ 
ing at Pizza’s ValidateDragAndDrop method. 


BRAGINFO and BRAGITEM 

Any method related to drag (or any drag message in a PM program) will 
receive a DRAGINFO structure, which consists of the following fields: 


cbDraglnfo 

sizeof(DRAGINFO) 

cbDragltem 

sizeof(DRAGITEM) 

usOperation 

(See Table 26-3) 

hwndSource 

Container object 

xDrop 

x coordinate of operation 

yDrop 

y coordinate of operation 

cditem 

Count of items dragged 

usReserved 

Reserved 
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xDrop and yDrop indicate the hot-spot—the exact target of a drop operation, 
were it to occur at that instant. Or, if this structure was built in response to 
the user dropping the object, they indicate the point where the objects were 
dropped. 

More than one object can be dragged and dropped at a time, as the cditem 
field reminds us. 

The usOperation may consist of any combination of the operations shown in 
Table 26-2. 


Table 26-2 Possible Drag Operations 

Symbol 

Meaning 

DCLDEFAULT 

Execute the default operation. 

D0_C0PY 

Copy. (Ctrl is pressed.) 

DOJJNK 

Shadow. (Ctrl+Shift is pressed.) 

DOJVIOVE 

Move. (Shift is pressed.) 

DOJJNKNOWN 

An unknown operation has been requested. 


The DO_UNKNOWN makes it possible for you to specify a new operation 
based on modifier keys. So if you want Ctrl+Alt+Shift to copy the topping 
over, but cut the calorie value of it in half, you can do so. In other words, you 
can directly affect the object being transferred, or do whatever you want to 
do, really. 



Knowing these codes also makes it possible for you to remove from your 
object certain types of actions. You can’t, for example, drop a copy of an 
object onto the shredder. 

WPS creates the DRAGINFO structure, telling you what has been requested 
by the user. 

The main thing we’ll use DRAGINFO for, however, is to gain access to the 
DRAGITEM structure. 
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The HSTR types listed in Table 26-3 are not really strings but handles to 
strings. The actual string data must be fetched using DrgQueryStrName, 
shown in the Code example following the table. 


Table 26-3 The DRAGSTEM Structure 

Type 

Description 

hwndltem 

Source of drag 

ulltemID 

Item identifier 

hstrType 

Type description 

hstrRMF 

Rendering description 

hstrContainerName 

Container name 

hstrSourceName 

Source object name 

hstrTargetName 

Suggested object name in target 

cxOffset 

Horizontal offset from hot spot to image 

cyOffset 

Vertical offset from hot spot to image 

fsControl 

(See Table 26-4) 

fsSupportedOps 

(See Table 26-5) 


You have to care about all this stuff in a non-WPS application. And, since the 
information given in this structure can be interesting (even in a WPS app), 
I’ve included the following code that you can plug into your wpDrop method 
to find out the nature of the object being dropped: 



DrgQueryStrName(di->hstrType,100,obj); 
DrgQueryStrName(di->hstrRMF,100,ren); 
DrgQueryStrName(di->hstrContainerName,100,con); 

DrgQueryStrName(di->hstrSourceName,100,src); 
DrgQueryStrName(di->hstrTargetName,100,trg); 
sprintf(msg, 

"ID:%d\nDESKTOP=%d\nObj:%s\nRen:%s\nCon:%s\nSrc:%s\nTrg:%s\n", 
di->ulItemID, b, obj, ren, con, src, trg); 

DebugBoxC"Validate", msg); 

DebugBox is a macro that calls WinMessageBox. (See Chapter 9.) 
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One of the first things you’ll find out is that whatever RMF is, it’s not simple. 
This is the “rendering format”—basically it is the protocol used by the 
source and the target to communicate with each other. 

The container name will be DESKTOP, or something like that, the source 
name (if you’re dragging the Anchovies topping) will be Anchovies, as will 
the target name. And the type of the object will be unknown! 

From this we can ascertain that this isn’t the SOM and WPS object type. It is the 
program file type , essentially. So if you dropped a .C file, the object type would 
appear to be something like “C program”. (See Chapter 22 for information on 
how to create a new program file type.) We’ll have to use some other means to 
determine whether or not the object dropped on the pizza is a topping. 

The fsControl field has one or more of the options shown in Table 26-4 set. 


Table 26-4 fsControl Flags 


Option 

Description 

DCJDPEN 

Object is open 

DC_REF 

Reference to another object 

DC_GR0UP 

Group of objects 

DC_CONTAINER 

Container of other objects 

DC_PREPARE 

Send DM_RENDERPREPARE before data transfer 

DC.REMOVEABLEMEDIA 

Indicates that the object is either on removable 
media, or cannot be recovered after being moved 


And the fsSupportedOps field lets you know what is allowed by the source. 
Table 26-5 shows the fsSupportedOPs options. 


Table 26-5 fsSupportedOps Flags 


Option 

Description 

D0_C0PYABLE 

Okay to copy 

DOJJNKABLE 

Okay to shadow 

DOJVIOVEABLE 

Okay to link 


Neither of these options are particularly important to us because we are 
going to let WPS do all the work. (So WPS can worry about removable media 
and whether or not copying is allowed.) 
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Basic drag-and-drop mechanics 

Now, I do think this information is important, or I wouldn’t have included it. If 
nothing else, it gives you some idea of how much easier it is to do things 
under WPS than “rolling your own” in PM. 

Basically, in a WPS object, if we want to control what happens when a drag or 
drop operation occurs over our object, we override the wpDragOver and 
wpDrop methods. 

We can also override the wpDragLeave method, if we do something special in 
wpDragOver that we want to undo when the user has dragged away from our 
object. WPS does this to highlight and de-highlight target objects. 

To limit a drag, we have to get a PDRAGINFO structure for each object being 
dragged and verify that it meets our criteria for an object to be dropped on 
our object. 

To do something special on a drop, we must look at each object being 
dropped and act accordingly on that object. 

Here is the ValidateDragAndDrop method for Pizza: 

S0M_Scope BOOL SOMLINK ValidateDragAndDrop!Pizza *somSelf, 
Environment *ev, PDRAGINFO pdrglnfo) 

{ 

PDRAGITEM di; 

char obj[100], ren[100], con[100], src[100], trg[100], 

msg[1000]; 

int 1, nobj; 

WPObject ^dropped; 

PSZ class; 

/* PizzaData *somThis = PizzaGetData(somSelf); */ 

PizzaMethodDebug("Pizza","ValidateDragAndDrop"); 

nobj = DrgQueryDragitemCount!pdrglnfo); 
ford = 0; i < nobj; i = i + 1) { 

di = DrgQueryDragitemPtr!pdrglnfo, id- 

dropped = OBJECT_FROM_PREC(di->ulItemID); 
class =(PSZ)_somGetClass Name!dropped); 

if (stremp!cl ass, "Topping")) return(FALSE); 

} 



return(TRUE); 
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You can see the code finding out the number of objects (DrgQueryDragltem- 
Count), and then iterating over each object to get a DRAGITEM structure for 
it, to get a pointer to the SOM object, and finally to get the class name. 

OBJECTJFROM_PREC is a handy little macro that finds the object pointer 
from the ID passed in DRAGITEM. And the SOM method _somGetClassName 
identifies the class of a given pointer. 

From there we only need to return FALSE if it’s not a Topping, and TRUE oth¬ 
erwise. What could be simpler? 

I lied at the beginning of the chapter, by the way—we don’t really need to 
override wpDrop. If an object fails the wpDragOver test, it will never be 
dropped. You need to override wpDrop only if you’re going to take some 
action when an object is dropped, which we don’t need to do. 


A Different (/ieu> 

As you can see, a WPS application isn’t as you can see, a monolithic .EXE that 
runs without considering other things on the Desktop. It is part and parcel of 
the user’s Desktop. In many cases, however, simple objects and containers 
(with their various views) aren’t going to be enough to express the program 
logic. 

You might have trouble, for example, making a WPS word processor out of 
letter objects and document objects. Or making a spreadsheet-type applica¬ 
tion out of number objects. 

But even with our pizza making simulation, or a like application, we may need 
more than WPS automatically gives us. We may need a different view of the 
object. 

Setting up the mW c lieW 

In order to add a new view, we also need to add a new menu item for the 
view. This involves overriding the menu methods, as covered in Chapter 24, 
and also overriding the wpOpen method. We also need to add new defines for 
the menu and View Pizza command. 

We’ll also need a special define to differentiate our pizza view from standard 
views. User views are defined as constants over the value OPENJJSER. 

(Other open values are things such as OPEN_SETTINGS and OPEN_TREE. 
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interface M_Pizza; 
interface Pizza : WPFolder 


BOOL ValidateDragAndDrop(in PDRAGINFO pdrglnfo); 


#ifdef _SOMIDL_ 

implementation { 


releaseorder : ValidateDragAndDrop; 

majorversion = 1; 
minorversion = 1; 
metaclass = M_Pizza; 


passthru C_ih_before = 
#define INCL_WINWORKPLACE 
#include <os2.h>" 


'#define 

PIZZAICON 

100" 

'#define 
'#define 

MID_PIZZAVIEWMENU (WPMENUIDJJSER+1) 

CMD_PIZZAVIEW (WPMENUID_USER+2) 

'#def i ne 

OPE N_PIZZA 

(OPENJJSER+1)" 


//# Method Modifiers 

wpDragOver 

wplnitData 

wpModifyPopupMenu 

wpMenuItemSelected 

wpOpen 


override; 
override; 
override; 
override; 
override; 


#endif 
}; 



Note that in this case, for simplicity, we’re not going to create a new filter 
method, as we did in Chapter 24. That means that ancestors of the Pizza class 
will be stuck with the PIZZAVIEW menu option. 

The .RC file will also have to include a menu definition, of course: 


#i nclude 


"pizza.ih 
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POINTER PIZZAICON pizza.ico 

MENU MID_PIZZAVIEWMENU 
BEGIN 

MENUITEM "-Pizza View", CMD_PIZZAVIEW 
END 

Just in case you’ve forgotten, here’s how you add an item to a menu: 

S0M_Scope BOOL SOMLINK wpModifyPopupMenu(Pizza *somSelf,... 

{ 

/* PizzaData *somThis = PizzaGetData(somSelf); */ 

PizzaMethodDebug("Pizza","wpModifyPopupMenu"); 

_wpInsertPopupMenuI terns (somSel f, hwndMenu, iPosition, hModule, 
MID_PIZZAVIEWMENU, WPMENUID_0PEN); 

return (Pizza_parent_WPFolder_wpModifyPopupMenu(somSel f, ... 

This adds the PIZZAVIEWMENU to the OPEN submenu. Now, we have to act 
on that item being selected: 

S0M_Scope BOOL SOMLINK wpMenuItemSelected(Pizza... 

{ 

/* PizzaData *somThis = PizzaGetData(somSelf); */ 

PizzaMethodDebug!"Pizza","wpMenuItemSel ected"); 

switch(MenuId) 

{ 

case CMD_VIEWPIZZA: 

_wpViewObject!somSelf, NULLHANDLE, OPEN_PIZZA, 0); 
break; 

1 

return(Pizza_parent_WPFolder_wpMenuItemSelected(somSelf,... 

} 

The _wpViewObjeet method takes the object to be opened as the first para¬ 
meter, the third parameter is an identifier for the view (which can be 
OPEN_SETTINGS, or whatever, as discussed on page 397), and the fourth 
parameter can be a parameter passed to wpOpen. 

The second parameter can be used if you have a specific view of the object 
that you want to surface. (You’ve stored the handle for the view somewhere 
and now you want it shown again.) 
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Hey, wait a minute! We didn’t call wpOpen at all. There’s a good reason for 
this. If you call wpOpen directly, and there’s an identical view of your object 
already open, you’ll end up opening another copy of the same view. (This 
can be handy, but it is usually not the desired action.) 

The wpViewObject method will either surface an existing view or create a 
new one, based on what the user has set on the Window settings page. 

All right, so what is in the wpOpen method? Well, I like to have my open 
methods look like this: 

S0M_Scope HWND SOMLINK wpOpen(Pizza *somSelf, HWND... 

{ 

/* PizzaData *somThis = PizzaGetData(somSelf); */ 

PizzaMethodDebug("Pizza","wpOpen"); 

switch (ulView) 

{ 

case OPEN_PIZZA: 

if (!_wpSwitchTo(somSel f, ulView)) 
return InitPizzaView(somSelf); 
break; 

default: 

return (Pizza_parent_WPFolder_wpOpen(somSel f, 
hwndCnr, ulView, param)); 

break; 


The first thing we do when receiving an OPEN_PIZZA is try to switch to an 
open Pizza View. If that fails, we must have to create a new Pizza View, which 
is what InitPizzaView does. Now note that the return from wpOpen is an 
HWND. 

What do you suppose InitPizzaView does? 

Take a look: 

HWND InitPizzaView(Pizza *pizza) 


HAB 

hab; 

/* 

anchor 

block handle 

*/ 

HWND 

hwndFrame, hwndClient; /* 

handles 

to windows 

*/ 

QMSG 

qmsg; 

/* 

message 


*/ 

char 

szClassName[] 

= "PizzaView" 




ULONG 

f1FrameOpts = 

FCF_STANDARD 

& ~FCF_ 

ICON & 
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~FCF_MENU & ~FCF_ACCELTABLE; 

PWINDOWDATA p; 

hab = WinQueryAnchorB1ock(HWND_DESKTOP); 

WinRegisterClass(hab, szClassName, ClientWndProc, 

CS_SIZEREDRAW, 4); 

hwndFrame = WinCreateStdWindow(HWND_DESKTOP, WS_VISIBLE, 

&f1FrameOpts, szClassName, 

, 0 L, 0, 0, 

&hwndClient); 

p = mal1oc(sizeof(PWINDOWDATA)); 
p->so = pizza; 

WinSetWindowPtr(hwndClient, 0, p); 
p->UseItem.type = USAGE_OPENVIEW; 
p-> Viewltem.view = OPE N_PIZ ZA; 
p-> Viewltem.handle = hwndFrame; 

_wpAddToObjllseLi st(p->so, &p->UseItem)) 

_wpRegisterView(p->so, hwndFrame, _wpQueryTitle(p->so))) 

WinShowWindow(hwndFrame,TRUE); 

WinSetFocus(HWND_DESKTOP, hwndFrame); 

return hwndFrame; 

} 


Look familiar? The process for creating a window in a WPS application—even 
though it’s called a view —is really no different from creating a window in a 
non-WPS application. 



In some ways, it’s easier: You query the Desktop’s anchor block instead of 
getting your own, and you don’t have to create a message queue, nor do you 
have to create an event loop. You’re using the Desktop’s event loop. 

You might create your own message queue, however, since this better pro¬ 
tects the Workplace Shell from bugs in your program. 

When you return a window handle from wpOpen, the Desktop inserts it into 
its views. 


There is a little bit more overhead, however, in other areas. For example, you 
need to call WinShowWindow, because the view will not automatically dis¬ 
play itself, and WinSetFocus, because the view will not automatically be 
focused. 


At a minimum you need to declare a structure like the following for your WPS 
views: 
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passthru C_h_after = 

" typedef struct " 

{" 

" Pizza *so;" 

USEITEM Useltem;" 

VIEWITEM Viewltem;" 

" } WINDOWDATA;" 

" typedef WINDOWDATA *PWINDOWDATA; 


(As you can see, I’ve chosen to define it in the .IDL file.) 

The USEITEM structure is used by wpOpenView to keep track of views that 
are currently open. You have to both add the view to the object’s use list and 
register the view. (This can be a mechanical process for now, at least until 
you feel really comfortable with WPS.) 

_wpAddToObjUseLi st (p->so , &p->llseltem)) 

_wpRegisterView(p->so, hwndFrame, _wpQueryTitle(p->so))) 


The rest of the overhead comes in the client window procedure’s 
WM_DESTROY handler: 

MRESULT EXPENTRY ClientWndProc(HWND hwnd, ULONG msg, MPARAM mpl, 
MPARAM mp2) 


HAB hab; 

HPS hps; 

RECTL rcl ; 

char text[] = "Hello, World"; 

LONG len; 

HWND hwndFrame; 

PWINDOWDATA wd; 

/*event handler*/ 
switch(msg) { 
case WM_PAINT: 

hps = WinBeginPaint(hwnd, NULLHANDLE, NULLHANDLE); 

WinQueryWindowRect(hwnd, &rcl ); 

WinFi11Rect(hps, &rcl , CLR_BACKGROUND); 

GpiSetBackMix(hps , BM_OVERPAINT); 

WinDrawText(hps, -1, text, &rcl, CLR_RED, CLR_GREEN, 
DT_CENTER | DT_VCENTER); 

WinEndPaint(hps); 
return 0; 
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case WM_CL0SE: 

hwndFrame = WinQueryWindow(hwnd, QW_PARENT); 
hab = WinQueryAnchorBlock(HWND_DESKTOP); 
wd = WinQueryWindowPtr(hwnd, 0); 

_wpDeleteFromObjUseList(wd->so, &wd->UseItern); 
WinPostMsg(hwnd, WM_QUIT, 0, 0); 

WinDestroyWindow(hwndFrame) ; 
return 0; 


/*end event handlers */ 

return WinDefWindowProc(hwnd, msg, mpl, mp2); 
} 


The clean up for the window is located in WM_DESTROY, instead of in a main 
program loop. You delete the object from the use list, free up the memory, 
and you’re done. (You don’t need to de-register—that happens automatically 
when the window closes.) 

It is important to post a WM_QUIT message to your window, because 
otherwise it will not know to go away. And there is no way to get rid of it 
otherwise! 


If you delete an object that currently has open views from the Desktop, the 
views will close automatically. 


Conclusion: Full Circle 

You see, we have finally come full circle! You learned about basic PM, mes¬ 
sages, controls, and so forth. Then, as you’ve read these chapters, you’ve 
learned about what must seem like a brand new API. 

But as you can see, the two approaches are complementary. WPS is an inter¬ 
face you can use to integrate your PM programs into the Desktop, if you like. 

It can be amazing when it all comes together! 
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in This Part «. 


erem I give alternatives to C and C++ for those of 
you seeking to expand your horizons or simply to 


flee from the industry’s languages of choice. Chapter 27 
lists ten non-C languages (not counting Assembly). 

Also, you are now officially an OS/2 initiate: You know 
your way around a window procedure. If you survived 
the last few chapters on the Workplace Shell, you know 
quite a bit more about OS/2 programming than you may 
realize. 

To push you onward, I make ten suggestions in Chapter 28 
about topics you might research in your pursuit of OS/2 
mastery. 




Chapter 27 

Ten Alternatives to C and C++ 

In This Chapter 
Compiled languages 
Interpreted languages 
Phone numbers 


/ make no bones of the fact that I am not a big C and C++ fan. And I confess 
that my prejudice is at least partly due to my own limitations. 

However, I’m the kind of guy who would trade compactness for readability 
any day, and I dislike programming language idioms. I’m also a guy who likes 
choices. 

So in case you feel like you have no choice but to program in C or C++, here 
are some alternatives. 


Pascal 

Niklaus Wirth created the Pascal language in the 70s, and his language 
remains to this day the clearest and one of the most clearly defined lan¬ 
guages ever written. 

Common dialects of Pascal are a little less clear, but they still retain most of 
the essential readability that is the hallmark of Pascal. Cabot, Clarion, Speed- 
Soft, and Prospero supply Pascal compilers. 


Cabot and SpeedSoft compilers are Borland-compatible and hence contain 
extensions to the original language to allow object-oriented programming. 
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PL/I 

The idea behind PL/I was to make the programmer’s life as easy as possible. 
Because of this, PL/I has a very simple and powerful syntax, and a very large 
language definition. 

Don’t let that scare you off, because it is a joy to work with a language based 
on that philosophy. 


Smalltalk 

Isn’t it about time that you tried a pure object-oriented language? Smalltalk is 
far and away the most popular pure 00 language in use today, and with good 
reason. Smalltalk syntax can be easily described in just a few pages, which 
makes it a great beginner’s language. 

Smalltalk’s biggest drawback is that it is egocentric. It sets up what is called a 
“virtual machine” on your computer, and this machine contains all your pro¬ 
grams and consumes a lot of disk space. Smalltalk also tends to be slow rela¬ 
tive to compiled languages. 

By the way, both Digitalk and IBM’s Smalltalk offerings do allow you to access 
the API directly, but this is not the most common or the easiest approach to 
use. 


REXX 

REXX under OS/2 is very much like BASIC in the DOS/Windows environment, 
except that its definition is much more tightly controlled and understood. 
REXX environments, however, are not compiled and they cannot access the 
OS/2 API directly. 

The current version of REXX is not object oriented, either, so there is no 
object framework. Instead, each Visual REXX environment has its own API 
that you must learn. Fortunately, this tends to be an easy task, because the 
calls are very straightforward. 

00 REXX is coming, and I hope it will resolve some of these problems. Even 
so, these visual REXX tools can be at least as productive under OS/2 as BASIC 
can be under Windows. 



Chapter 27 Ten Alternatives to C and C++ m 


Prolog 

Prolog was designed to ease the implementation of artificial intelligence-type 
programs, and as such the structure of Prolog is a little different. But this has 
an interesting organizational effect on Prolog PM programs: Instead of a giant 
client window procedure with a giant case statement, in Prolog you have 
many small procedures, which are invoked for the appropriate cases. (You 
may want to check out the disk to see what I mean.) 


And the Rest 

These are languages I have little or no experience with, but which are avail¬ 
able for OS/2 now, or will be shortly. There is a boom in OS/2 development 
tools going on at the moment, and by the year’s end (1995), we should see a 
plethora of new tools not mentioned here. 


Modula-2 

Modula-2, Niklaus Wirth’s follow-up language to Pascal, never caught on in a 
big way but there are some OS/2 compilers available for it from various 
sources. 


BASIC 

BASIC is unlikely to be a big player in OS/2 as long as REXX is around. They 
cover much the same territory. REXX, of course, comes with OS/2 and is 
0S/2’s official batch/macro language. However, Computer Associates has a 
Visual Basic-like product called CA-Realizer, and IBM itself is rumored to be 
readying a Visual Basic clone. 


Miscellaneous others 



Other languages that you might find around: COBOL, Oberon (Wirth’s follow¬ 
up language to OS/2), FORTRAN, and even Assembly. The only assemblers I 
know of and have used are the one that comes with Borland’s C compiler and 
the one that comes with SpeedSoft’s SpeedPascal/2. 

IBM may be discouraging the use of Assemblers because OS/2 code written in 
assembly won’t be portable to their PowerPC line of computers. 
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Addresses 

Here are the addresses of vendors mentioned in this chapter, so that you can 
try some of this stuff: 

Borland International, Inc. 

100 Borland Way 
P.O. Box 660001 
Scotts Valley, CA 95067-0001 
Tel: 1-800-645-4559 
Compiler: C/C++ 

Cabot Software 
The Vicarage 
Stoke View Road 
Fishponds, Bristol, BS16 3AE 
England 

Tel: 0117 958 6644 
Fax: 0117 958 6650 
CompuServe: 100014,241 

Compilers/Interpreters: Pascal, Modula-2, C, FORTRAN 

Clarion Software Corp„ 

150 E. Sample Rd. 

Pompano Beach, FL 33064 
Sales phone: 305-785-4555 
Fax: 305-946-1650 

Compilers: Modula-2, Pascal, C/C++ 

Computer Associates International, Inc. 

One Computer Associates Plaza 
Islandia, NY 11788 

Sales phone: 516-342-5224, 1-800-CALL-CAI 
Fax: 516-342-5734 

Interpreter: Basic dialect (CA-Realizer) 

OevTecti 

308 Springwood Road 
Forest Acres, SC 29206-2113 
Tel: 803-790-9230 
Fax: 803-738-0218 

Product: DeskMan/2 (with the Black Hole and more!) 
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Digitaik Inc. 

9841 Airport Boulevard 
Los Angeles, CA 90045 
Tel: 1-800-888-6892, 310-645-1082 
Fax: 310-645-1306 
CompuServe: 71610,1640 
Interpreter/GUI Builder: Smalltalk 

Gpf S 3 'stems, Inc. 

30 Falls Rd. 

Moodus, CT 06469 
Sales Phone: 203-873-3300 
Fax: 203-873-3302 
CompuServe: 72662,50 
GUI Builders: REXX, C/C++ 

HockWare 

315 N. Academy St., Ste. 100 

Cary, NY 27513 

Sales phone: 919-380-0616 

Fax: 919-380-0757 

GUI Builders: REXX, C/C++ 

IBM Corporation 
1000 NW 51st St. 

Boca Raton, FL 33429 

Compilers: PL/I, C/C++ (also a version of COBOL pending, and a 
long-dormant version of Pascal) 

Interpreters: Smalltalk, VisualGen 

GUI Developers: VisualAge (for Smalltalk), VisualGen 

Microway 

P.O. Box 79 
Kingston, MA 02364 
Tel: 508-746-7341 

Compilers: FORTRAN, C/C++, Pascal 

Prominare Inc. 

Toronto, Ontario 
Canada, M5A 4M8 
Fax: 416-363-6157 
CompuServe: 70363,1175 
GUI Builder: Prominare Designer 
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SpeedSoft 

19528 Ventura Blvd. #133 
Tarzana, CA 91356 
Tel: 818-887-3034 
Compiler: Pascal (w/Assembler) 

Watcom 

415 Phillip Street 
Waterloo, Ontario 
CAN N2L 3X2 
Tel: 519-886-3700 
Fax: 519-747-4971 
CompuServe: GO WATCOM 
Compilers: C/C++ 

GUI Builder: VX-REXX 


Conclusion 

The point, is that there are always other choices, and sometimes they are 
better than the obvious or easy ones. 

You can even buy a YACC (Yet Another Compiler Compiler), which turns a 
language description into a language compiler. YACC turns the source code 
of any language into C, which can then be compiled into native machine 
code. So if you’re not happy with your choices, you can always write your 
own language! 



Chapter 28 

The Future 


h This Chapter 

SOM++?? 

Multimedia possibilities 
More OS/2 API 


mo, you’ve started down the path of OS/2 programming! I hope that you’ve 
learned enough to be able to manage the mountains of documentation 
that accompany OS/2 and related topics. 

With what you have you can do quite a bit, but there’s always more—and in 
this case, there’s a lot more. So here are a few topics you might consider 
investigating further. Most of these are worth a book of their own, and in 
some cases, books dedicated to the topics exist or will be published shortly. 


REXX 

Studying REXX is a no-brainer. It’s an easy language to learn and use, and 
your life in OS/2 can be made much easier by the proper use of REXX and var¬ 
ious REXX environments. 

One area in particular that you may want to study is how to build DLLs that 
can be called from REXX. If you make a REXX-callable DLL, you start with a 
market of everyone who has OS/2, because OS/2 comes with REXX and just 
about anybody can slap a few lines of REXX together to call your DLL. 

Another approach is to make your application REXX-aware. This allows you 
to use OS/2’s built-in REXX interpreter as a macro language for any applica¬ 
tion you build. 
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0S/2's Underbelly 

This book was mostly about PM programming, with a bit on WPS program¬ 
ming, and just a smidgen on the base OS/2 API. In Chapter 21 we talked about 
threads, processes, and sessions, but an entire API manages the way those 
elements of OS/2 interact with each other. For example, how does one ses¬ 
sion communicate with another? If memory is protected in OS/2, can one 
process share information with another? 

These questions are interesting because a lot of the answers fit client/server 
questions, too. OS/2 creates a logical isolation between sessions, but the API 
is set up so that the isolation may as well be physical. So, many of the same 
solutions apply not just to different sessions on one computer, but to ses¬ 
sions on different computers. 


The Graphics Programming Interface 

The Graphics Programming Interface is an amazingly powerful set of tools. 
For example, you can create a presentation space in whatever coordinates 
best suit your program, and then transform those coordinates into a real 
device. No more worrying about what resolution the monitor has: Just set up 
your coordinates the way you want them and OS/2 takes care of the rest. 

Also, you can set up your programs so that the same code you use to draw 
on the screen can produce a paper drawing, which is a cool thing indeed. 


The Workplace Shell 

I hope I’ve gotten you started writing your own WPS applications, and I hope 
the power of this tool is more impressive than frightening. The fact that pro¬ 
grams are written as individual objects that interact with the operating sys¬ 
tem directly, instead of as monolithic blocks of code, can make life easier on 
the user—and even on the programmer! 

Implementations of WPS and WPS development tools are still relatively imma¬ 
ture, but expect to see them get more and more sophisticated as time goes 
by, ultimately surpassing more traditional methods. Which brings us to... 
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BSOM 

DSOM is an acronym for Distributed SOM, which is a means for objects on dif¬ 
ferent computers to interact. This is a mind-boggling concept, since pro¬ 
grams (or object interactions, really) can be set up so that their execution 
depends on what machines they’re hooked up with. 

Imagine having a SOM query object that interacts with another SOM reply 
object on a remote server. You ask the same questions but the reply object 
answers differently based on its own capabilities. For example, maybe the 
user queries about pizza recipes, and the reply object—which could have 
access to the Internet, CompuServe, America On-Line, or whatever—answers 
the question. You provide uniform access to information regardless of the 
service. 

Beyond this still science-fiction aspect of DSOM, that people are using DSOM 
currently in real business applications. 


Taligent 

Taligent is, depending on who you talk to and when you talked to them, 
either the successor to OS/2 or a complementary layer that works on top of 
OS/2. The role of Taligent seems to have waned lately because of 0S/2’s unex¬ 
pected success. It was originally supposed to be an object-oriented OS, writ¬ 
ten from the ground up using 00 concepts. 

Now, however, it appears that it will use services provided by OS/2 (which 
may emerge from all this fuss with a different name) to create an 00 layer 
between OS/2 and the user. Kind of like the WPS, only more so, and presum¬ 
ably less awkward to work with from the purity of its approach. 

Taligent technology has been used recently to create the Taligent Application 
Frameworks, which are prewritten objects used to speed application devel¬ 
opment. 


Openboc 

Remember a few years ago when Microsoft was promising that with OLE 
you’d be able to embed spreadsheets into your word processor documents, 
and so forth? That promise never really materialized in a big way, and is 
notoriously buggy, not to mention that is follows a completely proprietary 
Microsoft “standard.” 
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A large consortium of other software developers, including Apple and IBM, 
are supporting a genuine standard called OpenDoc, making this an important 
topic to read up on. 

Multimedia Extensions: the Unknown 
OS/2 Gold Mine 

One of 0S/2’s least-known cabilities is its prowess as a multimedia operating 
system. Its multithreading capabilities and DIVE interface (see the next topic) 
make it ideal for high-tech sound/video interaction. 

This is a profitable area—potentially dynamite, if properly exploited. What 
OS/2 user wouldn’t like to see some dedicated multimedia applications? And 
right now, all of the focus seems to be on business multimedia, like video- 
conferencing on your computer. (Which is great, but even OS/2 users need to 
have some fun!) 


MVE 


The Direct Interface Video Extensions API, or DIVE, is the latest addition to the 
multimedia extensions that are part of OS/2 Warp. In short, it makes graphics 
go fast. 

Now don’t, get this mixed up with WinG or with Windows’ feeble little multi- 
media add-ons. The multimedia extensions of Warp are part of the operating 
system. If you write a Windows 3.1 application using WinG, that application is 
not portable. 

DIVE, however, goes anywhere. Future versions of OS/2, wherever they may 
take us, should all support the DIVE interface. 

You can check out DIVE by running the DIVE sample app in the Warp Tool¬ 
kit’s Multimedia Sample Programs folder. 


Talkin' to l/our Computer 

For years and years, IBM has been working on voice recognition systems, and 
it finally seems that something is going to emerge from this effort. 
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IBM Personal Dictation Systems (IPDS) are going to bring speech recognition 
to OS/2, and in a big way. If you are working with any kind of data entry- 
oriented system, this will be something you’ll want to investigate. 


The PowerPC 

The PowerPC (PPC) chip is a great piece of hardware that may well take com¬ 
puter users into the 21st century. If it lives up to its promise, the PPC chip 
will accelerate the speed at which CPUs evolve. 

IBM has had this technology for quite a while but has yet to release a main¬ 
stream line of PCs for it. It is currently available running IBM’s AIX OS and 
Microsoft’s Windows NT, but neither of those operating systems can com¬ 
pare with Warp. 

Few PC users are interested in AIX, and of course, NT has yet to take off. No 
PowerPC user is going to accept DOS/Windows as the OS for their state-of- 
the-art computer. 

At the time of this writing, OS/2 for the PowerPC is being beta tested and is 
rumored to be scheduled for a summer ’95 release. If so, OS/2 may take off in 
a whole new direction. 

The beauty of this is that applications you write for OS/2 Warp need only be 
recompiled for the PowerPC to work. OS/2 is not a dead end by any stretch of 
the imagination. 


Conclusion 

So much to learn, so little time to learn it! Make no mistake: IBM has commit¬ 
ted its resources heavily to OS/2, despite what you may hear from the press. 

And, keep in mind that one thing hasn’t changed in this volatile industry: IBM 
has always said that OS/2 was the successor to DOS, while Microsoft has waf¬ 
fled between OS/2, Windows, NT, Chicago, and Cairo. 


OS/2 has been a sound choice for quite a while, so join the party—and get 
Warped! 




Glossary 


active: The active window is the one that 
receives keyboard input. 

ancestor: Any class from which another 
class inherits features. 

API: Application Programming Interface. 

application: Any combination and num¬ 
ber of code and data files used for a spe¬ 
cific purpose. A development environment 
application would consist of the compiler, 
the linker, the help system, and any other 
support programs that were included 
with it, as well as all of its data. (See also 
program.) 

Application Programming Interface: The 
means by which a programmer develops 
an application for a given environment. 
This can be as sweeping as the OS/2 PM 
API or WPS API, or as simple as a macro 
interface for a word processor. 

background task: A task that does not 
require user intervention to function 
properly. 

bind: To make a part of; combine. 

bitmap: A picture described in terms of 
what color each pixel is in each row and 
column. (Compare with vector Image.) 

bit masks: A series of zeros and ones 
where each digit (or set of digits) repre¬ 
sents the setting for a specific option. 

child window: Any window that is limited 
by another as to where it can draw itself. 
(Compare with top-level window.) 


class: In 00, a description of behaviors 
and data from which objects with similar 
functions can be created. In PM, see win¬ 
dow class. 

client: Any code that uses other code is a 
client to that other code. 

client window: The area where applica¬ 
tion-specific information is displayed, as 
distinguished from titlebars, menus, and 
other elements common to most PM pro¬ 
grams. 

command-line interface: A style of inter¬ 
acting with the computer in which the 
user types in commands and receives text 
feedback in a window that scrolls when 
full, as though the output were being 
printed on a typewriter. 

context: The state of the program at the 
time a request is made. 

control window: Any window that was 
designed to retrieve a particular type of 
data from the user. Basically any window 
that is neither a frame window nor the 
client window. 

cooperative multitasking: Multitasking 
that requires programmers to write code 
into their program that “gives up” the 
processor periodically so that other pro¬ 
grams may use it. (Compare with preemp¬ 
tive multitasking.) 

data validation: Verifying that the user’s 
input conforms to the data’s require¬ 
ments, e.g., when expecting a number 
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between 1 and 10, making sure the user 
hasn’t entered 11, or the letter Q. 

Desktop: The main window of the WPS 
which takes up the whole screen and 
which contains all other windows. 

device driver: A program written to con¬ 
trol a device, such as a printer or a moni¬ 
tor. 

dialog editor: A tool for interactively 
designing dialogs. 

direct manipulation: An emulation of 
physically moving and interacting with 
objects simulated on a computer using 
the mouse and pictures. 

double-click: To click the same button 
twice in rapid succession. (Not clicking 
two buttons at once.) 

event: Something that happens that a pro¬ 
gram is supposed to respond to. 

event-driven programming: The concept 
that programs should be created to 
respond immediately to events that might 
come at any time, as opposed to rigidly 
specifying when programs will accept 
input. 

feature: A data element or method of a 
class. 

flag: A specific element of a bit mask. 

focal point: The place where the user’s 
attention is fixed. 

font: A collection of instructions explain¬ 
ing how to draw characters and how to 
present those characters in relation to 
each other. 

framework: Any code set up to handle 
the unchanging aspects of a particular 


type of program. A framework can be an 
object class library, a set of function calls, 
or simply code that gets copied over. 

graphical user interface: an interface 
based on pictures and a pointing device. 
(Compare with command-line interface.) 

GUI: Graphical User Interface. 

handle: The act of responding appropri¬ 
ately to a message. 

hierarchy: A group of classes related by a 
common ancestor. 

icon: A small picture used to represent 
something else. 

inherit: Said of a class, and meaning to 
gain features from an existing class. 

instance: Any run-time occurrence of a 
particular class. 

MDI: Multiple Document Interface. 

message: Any question or command 
issued to another window. Messages 
often inform a window that an event has 
occurred. 

message queue: The place where PM 
places all messages for a window or 
thread. The message queue allows a 
thread to interact with PM and is the 
defining feature of a PM program. 

method: Code designed to create a spe¬ 
cific behavior for a class. 

modal: Working in a specific, limiting way. 

mode: A specific modal state. (For exam¬ 
ple, for a text editor, in insert mode you 
can only insert characters, while in over- 
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write mode you can only overwrite char¬ 
acters.) 

modeless: Not limiting. 

mouse: The most common pointing 
device, slid across a flat surface to move 
the screen pointer. Because the mouse is 
used so widely, the term is often used 
generically to mean any pointing device. 

Multiple Document Interface: An inter¬ 
face based on the user being able to open 
multiple child windows in an application- 
created common parent (or main win¬ 
dow) with the same functionality. Often 
the parent is a window that does nothing 
else but contain the other windows and 
supply a menu bar. (Compare with Single 
Document Interface-) 

multitasking: Doing more than one thing 
at a time. 

non-modal: See modeless. 

object: An instance of a given class. 

object-oriented: A philosophy of structur¬ 
ing programs around data and the behav¬ 
iors associated with that data. 

object-oriented graphical user interface: 
An interface based on the notion that 
interaction with computers can be made 
more intuitive by having the interface 
show objects that emulate real-world enti¬ 
ties, and that can be manipulated directly 
to perform the “expected” actions. 

OO: Object oriented. 

OOP: Object-oriented programming. 

OS/2: Operating System/2. 

parent: In PM, a window that provides 
boundaries within which other windows 


(its children) can draw themselves. In OO, 
a class that acts as the starting point for a 
new class, conferring upon the new class 
all of its features. (See also inherit.) 

PM: Presentation Manager. 

pointer: An on-screen indicator of the 
user’s focus. Also, the data structure that 
holds a picture of the indicator. 

pointing device: Any device that, when 
connected to a computer, allows the user 
to control a pointer on screen, and 
thereby enable direct manipulation of on¬ 
screen objects. 

preemptive multitasking: Multitasking in 
which the OS designates which program 
gets the processor without programmers 
having to write code to make that possi¬ 
ble. (Compare with cooperative multi¬ 
tasking-) 

Presentation Manager: The name of 
OS/2’s GUI API. Prior to OS/2 2.0, also the 
name of OS/2’s GUI. 

presentation space: A data structure rep¬ 
resenting both a space to draw on and 
characteristics used to draw primitives. 

primitives: Simple graphic elements used 
to create more complex images. The five 
graphic primitives are lines, markers, text, 
bitmaps, and areas. 

program: Sometimes used synonymously 
with application. A program more specifi¬ 
cally refers to a single executable file. The 
.EXE for a compiler is a program; the 
linker .EXE is another program. (See also 
application.) 

resource: A non-code description of some 
item that can be interpreted to create an 
object that code can interact with. 
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resource editor: A tool for interactively 
designing resources and resource files. 

resource file: A file containing one or 
more resources that can be bound in with 
an .EXE or .a DLL file 

scan code: The code sent from the key¬ 
board to the processor indicating what 
key has been pressed. (Scan codes may 
vary from keyboard to keyboard.) 

SDI: Single Document Interface. 

semaphore: A signal used to communi¬ 
cate between threads. 

Single Document Interface: An interface 
built of free-floating windows that are all 
children of the Desktop. (Compare with 

Multiple Document Interface.) 

SOM: System Object Model. 

standard window: In fact a number of 
windows, including a frame and client 
area, usually in addition to other windows 
such as a titlebar or menu bar. 

style: A particular option used in creating 
a window class. 

System Object Model: A protocol for cre¬ 
ating objects in a language-neutral fashion. 


task: Something to do or something done. 

thread: A unit of code in memory that 
OS/2 can execute. 

thumb: The indicator on a scroll bar 
which shows how deep in a particular 
field of data the current view is. 

top-level window: A window that has the 
Desktop as a parent. 

vector image: A picture described in 
terms of the lines needed to create it. 
(Compare with bitmap.) 

Warp: IBM’s name for OS/2 version 3.0. 

window: Any screen image that has an 
associated procedure to handle events. 

window class: A window procedure regis¬ 
tered with OS/2 and usually designed to 
serve a specific purpose. 

window word: Some data associated with 
a specific instance of a window class. 

Workplace Shell: The object-oriented GUI 
of OS/2. Also the SOM-based API for pro¬ 
gramming to that GUI. 
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* (asterisk), xxxv, 342 
\ (backslash), 325 

, (comma), 103, 104-105 
“ (double quotes), 103, 120 
... (ellipses), 379 
— (em dash), 93 
/ (forward slash), 342 

# (pound sign), 242 

~ (tilde character), 55 

• A • 

abstract objects, 357 
accelerator 

keys, 38, 119. See also hot 
keys 

tables, 103, 119-121, 125 
ACCELTABLE keyword, 119 
AddObjectWindowPage, 376 
AddSettingsPages, 379 
Alt+Esc, 126 
Alt+Fl, 4 

Alt+F4, 140, 141, 153, 170 
aMethod, 350 
AnchorBlockHandle, 32 
anchor blocks, 401 
handles to, 31-32 
registration and, 42-43 
AND, 22-23, 37 

API (Application Programming 
Interface), 3, 78, 123, 

180, 245-266 
buttons and, 188 
definition of, 419 
dialogs and, 151, 153 
DLLs and, 284, 286, 

289, 349 
menus and, 100 
OOP and, 336-337 
APIENTRY, 287, 289 
APIRET, 297 


application framework 
controls and, 168-171 
new basic, 142-145 
areas, definition of, 246 
arm, slider, 219, 220 
Arrange menu, 180 
ASCIIZ, 54 
Assembly, 409 
ASSOCFILTER, 328-329 
associating, program files with 
programs, 8, 328-329 
ASSOCTYPE, 328-329 
asterisk (*), xxxv, 342 
attributes 

defining fields as, 342-343 
extended (EAs), 125 
IDL, 342-343 

menu, dynamically setting, 
113-119 

• B • 

background color, 53-54, 
56-57. See also color 
BACKGROUND, 328 
backslash (/), 325 
BAREDIALOGID, 151 
BASIC, 321-322, 409 
BASIC2.C, 150, 246, 309 
BASIC2.H, 144, 150, 152, 281 
BASIC2.RC, 144, 150, 265 
BASIC2PROGRAMID, 150 
BBO.AND, 253 
BBOJGNORE, 253 
BBO_OR, 253 
BBO_PAL_COLORS, 253 
BEGIN, 102, 119 
bitmap(s), 123-132, 151 
adding, to dialogs, 172-174 
basic description of, 
130-132, 419 
erasing, 259 


fonts (raster fonts), 

254-255, 268, 272 
GPI and, 251-256 
menu items, 118-119 
mixed patterns and, 254-255 
bit masks, 22. See also flags 
basic description of, 419 
context menus and, 366 
menu attributes and, 116, 
117-118 

window styles and, 35-37 
BKA_MAJOR, 378 
BKA_MINOR, 378 
Black Hole, 391 
BLOCKS.BMP, 118 
BM_QUERY CHECK, 188 
BM_QUERYCHECKINDEX, 186, 
187, 188 

BM_QUERYHILITE, 188 
BM_SETCHECK, 188 
BM_SETDEFAULT, 186 
BM_SETHILITE, 188, 189 
BN_CLICKED, 188 
BN_DBLCLICKED, 188 
BonusPack, 8-9 
Boolean values, 23 
Borland International, 25, 100, 
149, 347, 410 
BOX.BMP, 118 
BSJ3STATE, 184 
BS_AUT03STATE, 184 
BS.AUTOCHECK, 184 
BS.AUTOCHECKBOX, 187 
BS_AUT ORADIOBUTT ON, 184 
BS.BITMAP, 185 
BS_CHECKBOX, 184, 187 
BS.DEFAULT, 185 
BS.HELP, 185, 186 
BSJCON, 185 
BSJV1INIICON, 185 
BS_NOBORDER, 185 
BS_NOCURSORSELECT, 
187-188 
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BSJNOPOINTERFOCUS, 185 
BS_PUSHBUTTON, 184 
BS.RADIOBUTTON, 184, 187 
BS_SYSCOMMAND, 185, 186 
BS.TEXT, 185 
BSJJSERBUTTON, 184-185 
buttons, 183-190 

check box specifics and, 

187- 188 

drawn in highlighted states, 

188- 189 

groups of, 186-187 
pushbuttons, 185-186 
radio buttons, 187-188 
spin buttons, 211-218 

• c • 

C programming, xxviii-xxx, 

23-25, 58, 72,100, 358-359 
building a settings notebook 
and, 380 

IDL data types and, 342 
macros and, 74 
manipulating objects and, 323 
menus and, 104 
SOM and, 342, 343, 345 
string data types and, 54 
ten alternatives to, 407-412 
C++ programming, 23, 25, 100, 
337, 342-345, 407-412 
Cabot Software, 410 
Cairo, 3 

callbacks, 178-179 
combo box, 207-208 
entry field, 195-197 
list box, 206-207 
slider, 226-229 
spin button, 216-218 
value set, 237-239 
case sensitivity, 322 
Cause-Effect dialogs, 

156-157, 179 
cb (field), 377 
cbDraglnfo, 392 
cbDragltem, 392 
CBM_HILITE, 208 
CBMJSLISTSHOWING, 208 
CBM_SHOWLIST, 208 
CBN_EFCHANGE, 208 


CBNJEFSCROLL, 208 
CBNJENTER, 208 
CBN_LBSCROLL, 208 
CBN_LBSELECT, 208 
CBN_MEMERROR, 208 
CBN_SHOWLIST, 208 
CBSJDROPDOWN, 207 
CBSJDROPDOWNLIST, 207-208 
cbSize, 146 
CBSJSIMPLE, 207 
cbWindowdata, 66 
CCVIEW, 327 
cditem, 392 
CDMJPROGRESS, 310 
CHAR, 120 
CHARIFROMMP, 82 
CHAR2FROMMP, 82 
CHAR3FROMMP, 82 
CHAR4FROMMP, 82 
characters. See also symbols 
\a, 103 
\n, 84, 293 
\t, 103 

len characters, 58 
line-continuation 
characters, 325 
underscore characters, 
347-348 

child windows, 19-22, 86, 110, 
419. See also inheritance 
CIDJBOXBITMAP, 173 
CL_MODE3, 275 
Clarion Software, 410 
class(es) 

basic description of, 18-19, 
41-42, 339 

client classes, definition of, 
41-42 

inheritance and, 19-22, 
339-340, 364-365, 390 
metaclasses, 378, 384 
clean-up code, 46 
client. See also client windows 
classes, definition of, 41-42 
code, definition of, 285 
client windows, 31, 37 
definition of, 419 
“Hello, World” program 
and, 53 

mapping window points 
and, 110 


ClientWndProc, 42-45, 48-49, 
66,71,74, 87,108,114, 155 
closing applications, 140-142 
CLR_BACKGROUND, 248, 249 
CLR_BLACK, 248 
CLRJBLUE, 248 
CLRJBROWN, 248 
CLR_CYAN, 248 
CLR_DARKBLUE, 248 
CLR_DARKCYAN, 248 
CLR_DARKGRAY, 248 
CLR_DARKGREEN, 248 
CLR_DARKPINK, 248 
CLR_DARKRED, 248 
CLRJDEFAULT, 248, 249 
CLRJFALSE, 248 
CLR_GREEN, 57, 248 
CLRJNEUTRAL, 248 
CLR_PALEGRAY, 248 
CLRJPINK, 248 
CLRJRED, 57, 248 
CLRJTRUE, 248 
CLR_WHITE, 248 
CLR_YELLOW, 248 
clsQueryModuleHandle, 378 
CLSSTYLE_DONTTEMPLATE, 
389-390 

CLSSTYLE_NEVERCOPY, 389 
CLSSTYLE_NEVERDELETE, 389 
CLSSTYLE_NEVERDRAG, 389 
CLSSTYLE_NEVERDROPON, 389 
CLSSTYLE_NEVERLINK, 389 
CLSSTYLE_NEVERM0VE, 389 
CLSSTYLE_NEVERPRINT, 389 
CLSSTYLE_NEVERRENAME, 389 
CLSSTYLE_NE VERSETTIN GS, 
389 

CLSSTYLE.NEVERTTEMPLATE, 

389-390 

CLSSTYLE_NEVERVISIBLE, 389 
CM_MODEl, 275 
CM_MODE2, 275 
CMD_BLOCKS, 119 
CMD_CHECK, 117-118 
CMD_DONE, 310, 313 
CMD_ENABLE, 117 
CMD_FILEDOIT, 313 
CMDJFILEOPEN, 153 
CMD_PROGRESS, 313 
CMD.VARIABLE, 116, 120 
COBOL, 338, 345, 409 
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color 

background color, 53-54, 
56-57 

changing default, 178 
constants (CLR_*), 52, 57, 
248-249 

drawing bitmaps and, 253 
“Hello, World” program and, 
52,53-55, 56-57 
indexes, 233 
PM system, 248 
presentation space, 52, 
53-55, 56-57 
RGB, 232, 248 
tables, logical, 248 
value sets, 232-234 
window classes and, 66 
combo boxes, 199, 207-209 
comma, 103, 104-105 
command lines, 24-25 
comments, 342 
compiling, xxx-xxxi, 358-359 
building a settings notebook 
and, 380 

command lines and, 24-25 
DLLs and, 292, 294 
menus and, 100 
SOM and, 340-343, 345, 
347-348, 353 

Computer Associates Interna¬ 
tional, 410 

CONFIG.SYS, 292, 323 

LIBPATH statement in, 347 
PATH statement in, 343 
context menus (pop-up menus), 
78-79, 107-113, 364-372 
contexts, of user actions, 17-18 
control(s), 21-22, 157-162, 
167-181 
styles, 174-176 
tab order and, 179-180 
window messages, 176-178 
window notifications, 
178-179 

CONTROL1, 211 
CONTROL1.C, 171, 183 
CONTROL1.H, 170, 199 
CONTROL1PROGRAMID, 170 
CONTROL1.RC, 173 
Control menu, 151 


coordinate systems, 19-21, 
34, 59 

mapping window points 
and,109-111 

rectangles and, 51 
CPUs (Central Processing 
Units), 299 

Crash Protection, 5-6 
CREATE_READY, 303-304 
CREATE_SUSPENDED, 303 
creation options, 38-31 
CS.CLIPCHILDREN, 43 
CS_CLIPSIBLINGS, 43 
CS.FRAME, 43 
CS_HITTEST, 43 
CS_MOVENOTIFY, 43 
CS_PARENTCLIP, 43 
CS.PUBLIC, 43 
CS.SAVEBITS, 43 
CS_SIZEREDRAW, 43 
CSJSYNCPAINT, 43 
Ctrl+Alt+Shift, 393 
Ctrl+C, 119 
Ctrl+D, 119 
Ctrl+Esc, 126 
Ctrl+Ins, 193 
Ctrl+O, 103 

CTXT_ARRANGE, 364-365 
CTXT.CLOSE, 364-365 
CTXT_COPY, 364-365 
CTXT.CREATEANOTHER, 
364-365 

CTXT.DELETE, 364-365 
CTXT_DETAILS, 364-365 
CTXT_FIND, 364-365 
CTXTJHELP, 364-365 
CTXTJCON, 364-365 
CTXT_LINK, 364-365 
CTXTJLOCKUP, 364-365 
CTXT_MOVE, 364-365 
CTXT_NEW, 364-365 
CTXT_OPEN, 364-365 
CTXT_PALETTE, 364-365 
CTXT.PRINT, 364-365 
CTXT_PROGRAM, 364-365 
CTXT_REFRESH, 364-365 
CTXT_SELECT, 364-365 
CTXTJSETTINGS, 364-365 
CTXT_SHADOW, 364-365 
CTXT_SHUTDOWN, 364-365 
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CTXT_SORT, 364-365 
CTXT_SWITCHTO, 364-365 
CTXT_TREE, 364-365 
CTXT_WINDOW, 364-365 
CUA (Common User Access), 
226, 237, 238 
cxOffset, 394 
cyOffset, 394 
Czaja, Gergory, 391 

• D • 

data 

types, 23-24, 342-343 
validation, 197, 419 
DBCS (double-byte character 
encoding schemes), 192 
DBM.NORMAL, 131 
DC_CONTAINER, 395 
DC.GROUP, 395 
DC_OPEN, 395 
DC_PREPARE, 395 
DC.REF, 395 

DC.REMOVABLEMEDIA, 395 
debugging, 139-140, 394. See 
also errors 

DEC_SEM_SHARED, 312 
DEFAULTICON, 125 
#defineINCL_GPI, 48, 63, 105 
DeScribe, 9 
DeskMan/2, 391,410 
Desktop 

changing icons on, 360-363 
Details view of, 331, 357 
Lockup pages, 376 
object IDs and, 322-323 
saving/restoring object data 
on, 384-386 
setting new views and, 
397-403 

DETAILSFONT, 328 
Details view, 328, 331, 357 
DETAILS VIEW, 328 
detent, slider, 220 
Developer’s Toolkit (RC.EXE), 
101, 294 

Developer’s Toolbox, 124 
device 

contexts, definition of, 257 
drivers, definition of, 5 
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DevOpenDC, 257 
DevTech, 410 

dialog(s). See also Dialog Editor 
basic description of, 133-148 
Cause-Effect, 156-157, 179 
controls, 157-162, 167-181 
creating your own, 150-152 
data, steps to using, 159-160 
File dialog and, 145-148, 155 
handling, improving, 180-181 
modal, 149, 153-154, 156, 
159-160, 163-164 
modeless, 163-164 
procedures, 154-157 
setting/getting window text 
and,161-162 
standard file, 133-134 
summoning/dismissing, 
153-157 

two principles of, 170 
DIALOG.C, 150 
DIALOG.DLG, 151, 152, 170 
Dialog Editor, 149, 151, 

172-173, 175, 180, 379 
entry fields and, 193, 194, 195 
radio buttons and, 187 
sliders and, 220 
spin buttons and, 214-215 
value sets and, 231, 242 
DIALOG.H, 150, 151 
DIALOGPROGRAMID, 150 
DIALOG.RC, 150, 151-152 
DIALOG.RES, 154 
DID_CANCEL, 146, 154 
DID_CAUSE, 156 
DID_EFFECT, 156 
DID_OK, 146, 154 
Digitalk, 411 

directives, releaseorder, 
348-350 
disabling 

the loading of the GUI, 4 
menu items, 117, 120 
DIVE (Direct Interface Video 
Extensions), 245, 

252-253, 266,416 
dlgid, 377 
dlgstruct, 196 
DLGTEMPLATE, 150 


_DLL_InitTerm, 289, 290 
DLLs (Dynamic Link Libraries), 
283-297, 359, 361-362, 
380, 383, 390 

basic description of, 284-285 
building a settings notebook 
and, 380, 383 
creating, 285-291 
metafiles and, 361 
module definition files and, 
285, 288-291 
SOM and, 349, 352-354 
storing resources in, 293-297 
using, 291-293 
DM_DRAGLEAVE, 238 
DMJDRAGOVER, 238 
DM_DROP, 238 
DM_DROPHELP, 238 
DO.COPY, 393 
DO.COPYABLE, 395 
DO.DEFAULT, 393 
DO_LINK, 393 
DOJLINKABLE, 395 
DO_MOVE, 393 
DOJVIOVEABLE, 395 
DOJJNKNOWN, 393 
DOS (Disk Operating System), 

4, 245, 321-322 
device drivers and, 5 
keyboard input and, 81, 82 
programming paradigms 
and, 15 

sessions, running, as full 
screen or windowed, 301 
traditional computing envi¬ 
ronments and, 12 
DosCreateThread, 303 
DosFreeModule, 296-297 
DosKillThread, 303 
DosLoadModule, 296-297 
DosQueryEventSem, 312 
DosQueryModuleHandle, 363 
DosResetEventSem, 312 
DosSuspendThread, 303-304 
double quotes (“), 103, 120 
dragging (drag-and-drop), 356 
direct manipulation and, 9 
DRAGIMAGE and, 392 
DRAGINFO and, 391-397 


DRAGITEM and, 391-397 
mechanisms, basic, 396-397 
in a non-Workplace shell 
application, 391-392 
starting/stopping, 78-79 
DrgQueryDragltemCount, 397 
Drives folder, 323 
DSOM, 415 
DT_BOTTOM, 54-55 
DT_CENTER, 54-55 
DTJERASERECT, 54-55 
DT_EXTERNALLEADING, 

54-55, 62 

DT_HALFTONE, 54-55 
DTJLEFT, 54-55 
DTJMNEMONIC, 54-55 
DT_QUERYEXTENT, 54-55 
DT_RIGHT, 54-55 
DT_STRIKEOUT, 54-55 
DT.TEXTATTRS, 54-55 
DT_TOP, 54-55 
DTJJNDERSCORE, 54-55 
DT_VCENTER, 54-55 
DT.WORDBREAK, 54-55, 58, 60 
Durant, Will, 277 



EAs (Extended Attributes), 125 
editors. See also Dialog Editor 
Enhanced Editor, 17-18, 
31,272 

Font Editor, 267, 271 
Icon Editor, 124-125, 126 
multiline editors (MLEs), 191 
resource editors, 149-152, 
154, 172, 180 
EF_DATA, 158 
ellipses (...), 379 
EM_CLEAR, 193 
EM_COPY, 193 
EM_CUT, 193 
em dash (-), 93 
EM_PASTE, 193 
EM_SETSEL, 193 
EM_SETTEXTLIMIT, 194, 195 
encapsulation, 339 
EN_CHANGE, 195 
EN_CLEAR, 194 



EN_COPY, 194 
EN_CUT, 194 
END, 102, 119 
Enhanced Editor, 272 

basic description of, 17-18 
client window in, 31 
ENJCILLFOCUS, 195, 197 
EN_MEMERROR, 195 
EN.OVERFLOW, 195 
EN_PASTE, 194 
EN_QUERYCHANGED, 194 
EN_QUERYFIRSTCH AR, 194 
EN_QUERYREADONLY, 194 
EN_QUERYSEL, 194 
EN_SCROLL, 195 
EN_SETFIRSTCHAR, 194 
EN.SETFOCUS, 195 
EN_SETINSERTMODE, 194 
EN_SETREADONLY, 194 
EN_SETSEL, 194 
EN_SETTEXTLIMIT, 194 
ENTRY dialog, 191 
entry field(s), 191-198 
callbacks, 195-197 
data validation and, 197 
sending messages to, 193-195 
Environment parameter, 345, 
346-347 

errors 

debugging and, 139-140, 394 
dialogs and, 138-140 
“file already open,” 72 
module handles and, 363 
“unresolved external,” xxx 
ES_AUTOSCROLL, 192, 193 
ES_AUTOSIZE, 192, 193 
ES_AUTOTAB, 192 
ES_CENTER, 192 
ES_COMMAND, 192, 193 
ES_LEFT, 192 
ES_MARGIN, 192 
ES_READONLY, 192 
ES_RIGHT, 192 
ES.UNREADABLE, 192, 193 
event-driven programming, 

16, 420 

event handlers, modal dialog, 
381-383 

EVENTS.C, 68-71 
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Events program, 65-86, 94 
EXENAME, 328 
EXPENTRY, 43, 287 
EXPORTS, 291 
extended selection, 200 
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FATTR_FONTUSE_NOMIX, 271 
FATTR_FONTUSE_OUTLINE, 
271,273 

FATTR_FONTUSE_TRANS- 
FORMABLE, 271,273 
FATTR_SEL_BOLD, 271 
FATTR_SEL_ITALICS, 271 
FATTR_SEL_OUTLINE, 271 
FATTR_SEL_STRlKEOUT, 271 
FATTR_SEL_UNDERSCORE, 271 
FCF_ACCELTABLE, 38, 39, 41 
FCF_AUTOICON, 38, 39 
FCFJBORDER, 38, 39 
FCF_DLGBORDER, 38, 39 
FCF_HIDEBUTTON, 39, 40 
FCF_HIDEMAX, 39 
FCF_HORZSCROLL, 39, 40, 85-86 
FCFJCON, 38, 39, 40,41, 125 
FCF_MAXBUTTON, 39, 40 
FCF_MENU, 38, 39, 40, 41 
FCF_MINBUTTON, 39, 40 
FCF_MINMAX, 39 
FCF_MOUSEALIGN, 39, 40 
FCF_NOBYTEALIGN, 39, 40 
FCFJMOMOVEWITHOWNER, 
39,40 

FCF_SCREENALIGN, 39, 40 
FCF_SHELLPOSITION, 39, 40 
FCF_SIZEBORDER, 38, 39 
FCF_STANDARD, 39, 41 
FCF_SYSMENU, 39, 40 
FCF_SYSMODAL, 39, 41 
FCF.TASKLIST, 39, 41 
FCF.TITLEBAR, 39, 41 
FCF.VERTSCROLL, 39, 40, 85-86 
FDS_APPLYBUTTON, 146, 147 
FDS.CENTER, 147 
FDS_ENABLEFILELB, 147 
FDS.HELPBUTTON, 147 
FDS_MODELESS, 146, 147 
FDSJMULTIPLESEL, 146-147 


FDS_OPEN_DIALOG, 147 
FDS_SAVEAS_DIALOG, 147 
fFormat, 361 
FID_CLIENT, 86 
FID_H0RZSCROLL, 86 
FID.MENU, 86 
FID_MINMAX, 86 
FID_SYSMENU, 86 
FIDJTITLEBAR, 86 
FID.VERTSCROLL, 86 
fields. See also entry fields 
basic description of, 339 
defining, as attributes, 
342-343 

FILEDLG, 145-148 
file extensions 
.DEF, 285 
.EXE, 101 
.RC, 100 
File Manager, 8 
filenames, semaphore names 
and, 311 
FIXED, 274 
fl (field), 146 
flags. See also bit masks 
basic description of, 

22-23,420 

frame creation (FCF), 38-41 
fsControl, 395 
fsSupported, 395 
flFrameOpts, 105 
folders. See also folders (listed 
by name) 

creating/opening, 324-325 
creating program files 
for, 326 

object IDs and, 323 
folders (listed by name) 

Drives folder, 323 
Hidden folder, 323 
Information folder, 323 
Startup folder, 323 
System folder, 323 
System Setup folder, 19, 75, 
80, 323 

Templates folder, 8, 323 
Font Editor, 267, 271 
FONT.H, 281 

FONTJDEFAULT, 271, 272 
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FONT_MATCH, 271 
FONTMETRICS, 61-63, 93, 

146, 273 

font(s), 93, 148, 267-282 
bitmap (raster fonts), 
254-255, 268, 272 
Courier, 277-278 
“Hello, World” program and, 
61-62 

logical, 270-273 
metrics, 281-282 
parent/child windows and, 
19-21 

rotation, 275-276, 277 
special text effects and, 
273-281 
Swiss, 282 

terminology, 270-273 
Times New Roman, 282 
vector (outline fonts), 268, 
272-281 

foreign languages, tab order 
and, 179 
FORTRAN, 409 
forward slash (/), 342 
frame windows 

creation options and, 38-41 
resizing, 18 

standard windows as, 30 
fsControl, 394, 395 
fsFontUse, 271 
fsSelection, 271 
fsSupportedOps, 394 

• G • 

Gates, Bill, 3 

_get_chorus(), 343, 347, 348 
get_copyright(), 342, 346 
_get_field(), 342 
GetNameO, 339, 340 
GliLine, 249 
Gpf Systems, 411 
GPI (Graphics Programming 

Interface), 30-31, 48, 123, 
245-266, 414 

“Hello, World” program 
and, 53 

line graphics and, 246-250 
GPIA.NOASSOC, 258 


GpiBitBlt, 251,253, 255-264, 
266, 269 

GPI.C, 259-264, 265 
GpiCharString, 269 
GpiCharStringAt, 269, 273 
GpiCreateLogColorTable, 248 
GpiCreateLogFont, 271-273 
GpiCreatePS, 256-258 
GpiErase, 52 
GPI.ERROR, 271 
GPIF_LONG, 258 
GPIF_SHORT, 258 
GpiFullArc, 250 
GPI.H, 264 

GpiLoadBitmap, 131, 173 
GpiMove, 249, 250 
GpiPolyLine, 250, 269 
GPI.RC, 264-265 
GpiQueryFontMetrics, 61, 273 
GpiQueryText, 269 
GpiQueryTextBox, 269, 276 
GpiSetBackMix, 56-57 
GpiSetCharAngle, 274-276 
GpiSetCharBox, 274 
GpiSetCharMode, 274 
GpiSetCharSet, 273 
GpiSetDefAttrs, 249 
GpiSetPattern, 255 
GPITJVIICRO, 258 
GPITJNfORMAL, 258 
GRAB.PTR, 126-128, 293, 297 
GRADIENTL, 274, 275 
groups, of buttons, 186-187 
GUI (Graphical User Interface), 
xxxi, 47-64. See also PM 
(Presentation Manager); WPS 
(Workplace Shell) 
input and, 82 
loading of, disabling, 4 
menus and, 99 
OS/2, basic description of, 
6-9 

PM messages and, 73 
use of windows in, 16-18 

• H • 

header files. See also 
specific files 
DLLs and, 285-286 


sempahores and, 313-319 
SOM and, 343, 351 
threads and, 309-310 
Hebrew language, 179 
HELLO.EXE, 326, 332 
HELLO program, 326, 332, 
329-330 

“Hello, World!” program, 

47-64, 65 

help 

menus and, 99 
WM_HELP and, 113, 120, 
185, 237 

HELPLIBRARY, 327 
HELPPANEL, 327 
Hidden folder, 323 
HIDEBUTTON, 327 
hierarchy, 355, 422 
highlighted buttons, 188-189 
HMODULE Resource, 42 
HMQ data type, 33 
HockWare, 411 

hot keys, 55, 103, 119-121. See 
also accelerator keys; 
accelerator tables 
HPFS (High Performance File 
System), 331 
hstrContainerName, 394 
hstrRMF, 394 
hstrSourceName, 394 
hstrTargetName, 394 
hstrType, 394 
HWND, 66 
HWND Client, 42 
HWNDJDESKTOP, 136 
hwndltem, 394 
hwndPage, 377, 378 
hwndSource, 392 

• / • 

I-beam, 126 

IBM (International Business 
Machines), 149, 411 
Class Library User Interface 
0CLUI), 28 

compilers, 24-25, 100 
voice recognition systems, 
416-417 

WorkFrame/2, 10-13, 101 



icon(s), 123-132 

adding, to dialogs, 172-173 
basic description of, 124-125 
changing class, 360-363 
creating program, 326 
editor, 124-125, 126 
options, WinMessageBox, 
136-137 

in Windows vs. in the 
Workplace Shell, 8 
ICON.CLEAR, 361 
ICON_DATA, 361 
ICONEDIT.EXE, 331 
ICON_FILE, 361 
ICONFILE, 327 
ICONFONT, 328 
ICONINFO, 361,364 
ICONPOS, 327 
ICON.RESOURCE, 361 
ICONVIEW, 328 
ICONVIEWPOS, 328 
ID_OPENMENU, 366 
IDE (Integrated Development 
Environment), xxx, 
100-101, 

150, 286, 289, 292, 294 
identifications (object IDs), 
322-323, 331 
identifiers, data type, 24 
IDL (Interface Definition Lan¬ 
guage), 338-351, 358-359, 
362, 366-368, 379, 387-388 
IMaxBaselineExt, 62 
IMPLIB.EXE, 292, 353 
IMPORTS, 292 
INCLJDOS, 296 
INCL.GPI, 28 
INCL_WIN, 28 
indexes 
color, 233 
list box, 203-204 
Information folder, 323 
inheritance, 339-340, 364-365, 
390,419 

child windows and, 19-22, 

86 , 110 

parent windows and, 19-22, 
34,37,86,110 
INITGLOBAL, 290 
initialization, 351, 353, 383-384 
INITINSTANCE, 290 


todex ($29 


InitPizzaView, 400-401 
input, 81-95 

four basic sources of, 65 
parent/child windows and, 86 
scroll bars and, 82-92 
system events and, 84-85 
timers and, 93-95 
installing, LaunchPad objects, 
331-332 

instances, definition of, 339 
integers 

32-bit, 35, 38, 54, 87, 94 
four-byte, 73 

LONG, 23, 213-214, 216, 257, 
258, 274, 364, 385-386 
SHORT, 258, 274 
IPDS (IBM Personal Dictation 
Systems), 416-417 

• 7 • 

Jones, Chuck, 265 
Juster, Norman, 265 

• K • 

KC_ALT, 83 
KC_CHAR, 83 
KC_COMPOSITE, 83 
KC_CTRL, 83 
KC_DEADKEY, 83 
KCJNVALIDCOMP, 83 
KCJCEYUP, 83 
KCJLONEKEY, 83 
KCJPREVDOWN, 83 
KC.SCANCODE, 83 
KC_SHIFT, 83 
KC.VIRTUALKEY, 83 
keyboard input, 81-95 
keystroke combinations 
Alt+Esc, 126 
Alt+Fl, 4 

Alt+F4, 140, 141, 153, 170 
Ctrl+Alt+Shift, 393 
Ctrl+C, 119 
Ctrl+D, 119 
Ctrl+Esc, 126 
Ctrl+Ins, 193 
Ctrl+O, 103 
Shift+FlO, 79, 109 


• L • 

languages, foreign, 179 
LaunchPad, 13-14, 331-332, 357 
lAveCharWidth, 271, 272, 282 
LBOXINFO, 204 
lEmHeight, 282 
lEmlnc, 282 
len characters, 58 
lExHeight, 282 
lExternalLeading, 282 
LIBPATH statement, 347 
libraries. See also DLLs 

(Dynamic Link Libraries) 
IBM Class Library User 
Interface, 28 
SOM (System Object 
Model), 352-354 
LIDJEXT, 199 
LID_MULT, 199 
LID_MULTEXT, 199, 205 
line(s), 246-250 

-continuation characters, 325 
styling, 247-249 
as “unruly squiggles,” 
249-250 

LINETYPE_ALTERNATE, 249 
LINETYPE_DASHDOT, 249 
LINETYPE_DASHDOUBLEDOT, 
249 

LINETYPE_DOT, 249 
LINETYPE_DOUBLEDOT, 249 
LINETYPEJNVISIBLE, 248 
LINETYPEJLONGDASH, 249 
LINETYPE_SHORTDASH, 249 
LINETYPE.SOLID, 249 
linking, dynamic vs. static, 
284-285. See also DLLs 
(Dynamic Link Libraries) 
llnternalLeading, 282 
list box(es), 199-209 

basic description of, 200-201 
callbacks, 206-207 
finding out which items are 
selected in, 204-205 
indexes, 203-204 
inserting multiple items 
in, 204 

messages, sending, 201-206 
searching for strings in, . 
205-206 
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LISTBOX.C, 204 
LIT_CURSOR, 205 
LIT_END, 203 
LIT_FIRST, 205 
LIT_NONE, 205 
LIT_SORTASCENDING, 203 
LIT_SORTDESCENDING, 203 
lltemlndex, 204 
lLowerCaseAscent, 282 
lLowerCaseDescent, 282 
LM_DELETEALL, 201, 202 
LM_DELETEITEM, 201, 202 
LMJNSERTITEM, 201, 202 
LMJNSERTMULTITEMS, 

201 , 202 

LM_QUERTYITEM- 

TEXTLENGTH, 202, 203 
LM.QUERYITEMCOUNT, 202 
LM_QUERYITEMHANDLE, 202 
LM.QUERYITEMSELECT, 

204- 205 

LM_QUERYITEMTEXT, 202, 203 
LM.QUERYSELECTION, 202, 205 
LM_QUERYTOPINDEX, 202 
LM_SEARCHSTRING, 202, 

205- 206 

LM_SELECTITEM, 202 
LM_SETITEMHANDLE, 202, 203 
LM_SETITEMHEIGHT, 202, 203 
LMJSETITEMTEXT, 202 
LM_SETITEMWIDTH, 202, 203 
LM_SETTOPINDEX, 202 
IMaxAscender, 282 
IMaxBaselineExt, 271, 282 
IMaxCharInc, 282 
IMaxDescender, 282 
IMaxsBaselineExt, 272 
LN_ENTER, 206, 207 
LNJCILLFOCUS, 207 
LN_SCROLL, 207 
LN_SELECT, 207 
LN_SETFOCUS, 207 
LOADONCALL, 101 
LONEKEY, 120 
LONG integers, 23, 213-214, 

216, 257, 258,274, 364, 

385-386 
IReturn, 146 

LRS (Long-Range Sensors), 231, 

233, 238 


LS_EXTENDEDSEL, 200 
LSJHORZSCROLL, 200 
LS_MULTIPLESEL, 200 
LS_NOADJUSTPOS, 200, 201 
LS_OWNERDRAW, 200, 206 
LSS_CASESENSITIVE, 206 
LSS_PREFIX, 206 
LSS_SUBSTRING, 206 
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macros, 74, 76, 274, 394 
MAHJONGG.ICO, 145 
MAKEFIXED, 274 
mapping, window points, 
109-111 

markers, definition of, 246 
MAXIMIZED, 328 
MB_ABORTRETRYIGNORE, 
136, 138 

MB_APPLMODAL, 137-138 
MB_CANCEL, 136, 138 
MB_DEFBUTTON 1, 137-138 
MB_DEFBUTTON2, 137-138 
MB_DEFBUTTON3, 137-138 
MB.ENTER, 136, 138 
MB_ENTERCANCEL, 136, 138 
MB.ERROR, 136, 138 
MB_HELP, 136, 138 
MBJCONASTERISK, 136 
MBJCONEXCLAMATION, 136 
MBJCONHAND, 136 
MBJCONQUESTION, 136 
MBJNFORMATION, 136 
MB_MOVABLE, 137-138 
MBJNfOICON, 136-137 
MB_OK, 136, 138 
MB_OKCANCEL, 136, 138 
MB_QUERY, 136 
MB_RETRYCANCEL, 136, 138 
MB_SYSMODAL, 137-138 
MB_WARNING, 136 
MB_YESNO, 136, 138 
MB_YESNOCANCEL, 136, 138 
MBID_ABORT, 138 
MBID_CANCEL, 138 
MBID_ENTER, 138 
MBID_ERROR, 138 
MBIDJGNOR, 138 
MBID_NO, 138 


MBID_OK, 138 
MBID_RETRY, 138 
MBID_YES, 138 

MDI (Multiple Document Inter¬ 
face), 10-11,21,422 
memory, 6, 101 

allotments of (window 
words), 66-67 
protected, 5-6 
RAM (random-access 
memory), xxix 
SOM clients and, 346-347 
threads and, 303 
menu(s), 99-122 

attributes, dynamically 
setting, 113-119 
command messages and, 113 
context menus (pop-up 
menus), 78-79, 107-113, 
364-372 

as control windows, 161 
coordinates, mapping, 
109-111 

describing, 101-105 
hot keys and, 119-121 
incorporating, 105-107 
items, bitmap, 118-119 
mapping window points 
and,109-111 

removing/adding items to, 
364-372, 399 

resource files and, 100-103, 
105, 107, 114, 118-119 
MENU.H, 105 
MENU2.H, 119 
MENUITEM, 102-103, 113 
MENU keyword, 101, 102 
message(s) 

basic description of, 16, 422 
boxes, basic description of, 
135-138 

list box, sending, 201-206 
mouse, 74-80 
notification, 178-179, 208 
PM, understanding, 72-74 
sending, to entry fields, 
193-195 
slider, 223-226 
spin button, 213-216 
value set, 234-236 



warning, 348-349 
window, 176-178 
MessageQueueHandle, 32 
metaclasses, 378, 384 
methods, definition of, 339 
MIA.CHECKED, 104 
MIA.DISABLED, 104, 117 
MIAJFRAMED, 104 
MIA.HILITED, 103-104 
MIA_NODISMISS, 104 
Microway, 411 
MID_ABOUT, 112 
MID_END1, 113 
MID_GRAPHICS, 119 
MID.STUFF, 112 
MINIMIZED, 328 
Minimized Window Viewer 
object, 125 
MINWIN, 327 

MIS_BITMAP, 103, 118, 119 
MIS_TEXT, 103 
MLE (multiline editor), 191 
MM.QUERYITEMATTR, 116 
MM_SETITEMATTR, 116 
modality, 8-9, 133-134, 137, 
420-421 
Modula-2, 409 
module definition files, 285, 
288-291 

mouse, 65-80. See also dragging 
(drag-and-drop); pointers 
events that may be related 
to, 78-79 

information, 75-76 
messages, 74-80 
MPARAM, 23-24, 73, 82, 238 
MPFROMSHORT, 87, 238 
MPFROMSHORT2, 87 
MRESULT, 87, 91 
multimedia extensions, 416-417 
MULTIPLE, 291 
multiple selection, 200 
multitasking, 299-300 
classes and, 18 
cooperative, 4, 419 
preemptive, 4, 421 
multithreading, 93-95 
MyProgram.EXE, 101 
MyRes.RC, 101 


Index 
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name(s) 
file, 311 

object, 325, 331 
physical object, 
displaying, 331 
semaphore, 311 
newline character (\n), 84, 293 
NOAUTOCLOSE, 328 
NOCOPY, 327 
NODELETE, 327 
NODRAG, 327 
NODROP, 327 
NO_ERROR, 297 
NOLINK, 327 
NOMOVE, 327 
NORENAME, 327 
NOSHADOW, 327 
NOT, 22-23 
notification messages, 

178-179, 208 
NOTVISIBLE, 327 
NOTWINDOWCOMPAT, 290 
NULLHANDLE, 50, 141, 257, 297 


• 0 • 

Oberon, 409 
object (s) 

IDs (identifications), 
322-323, 331 
opening, 78-79 
in OS/2, basic description 
of, 8-9, 337, 339 
saving/destroying, 330 
selecting single, 78-79 
OBJECT_FROM_PREC, 397 
OBJECTID, 327 
ODJMEMORY, 257 
OOP (object-oriented program¬ 
ming), 18-19, 336-337, 
339-340 
OPEN, 327, 328 
OpenDoc, 415 
OPEN_PIZZA, 400 
OPEN_SETTINGS, 397, 399 
OPEN.TREE, 397 
OPENJJSER, 397 


operating systems 

modal vs. modeless, 9 
as sources of input, 65 
operators, 104 
OR, 22-23, 36-37 
OS2.H, 28-29, 49, 103, 120 
OS/2.INI, 357, 385 
OS2LOGO.BMP, 130 
OS/2 Technical Library, 
300-301 

OS/2 Warp Toolkit, 25, 292, 

343, 347 

overriding methods, 350-351 
ownership, 21-22 

• P • 

PAGEINFO, 377-378 
pages (settings notebook). See 
also settings notebook 
adding, 377-378 
removing, 376-377 
Paintlt, 49, 53,57-59,71,72 
papszFQFileName, 146 
parameters 
flags and, 22 
presentation, 177-178 
WinCreateStdWindow, 34, 
37, 41-42 

PARAMETERS, 328 
parent windows, 19-22, 86. See 
also inheritance 
mapping window points 
and, 110 

window styles and, 34, 37 
Pascal, 337, 407 
PATSYM_VERT, 255 
PB.DISPLAY, 211 
PB.QUERY, 219, 231 
PCH, 54 
PCHAR, 54 

pCreateParms, 377, 378 
PDRAGINFO, 396 
pfnwp, 377 
PID_QUERY, 199 
PID_SEARCH, 199 
pixels, 61 

pizza-making programs, 
356-403 
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PL/I, 408 

PM (Presentation Manager) 
the application framework 
and,28-46 

basic description of, 7-8 
DLLs and, 290 
event-driven programming 
and, 16 
fonts and, 61 
GPI and, 245-266 
“Hello, World” program 
and, 53 

input and, 81-95 
LaunchPad and, 13-14 
messages, understanding, 
72-74 

mouse messages and, 80 
OOP and, 336-337 
pointers and, 126 
presentation spaces and, 
49-51, 53-57 
SOM and, 9, 346 
threads and, 305 
timers and, 93-95 
window words and, 66-67 
vs. WPS, 10-13 
PMWIN.DLL, 285, 289 
POINTER, 293 
POINTER.C, 126-130 
pointers, 123-132 

basic description of, 125-130 
mapping, 109-111 
system, 129-130 
POINTL, 247, 249, 251,253, 

269, 274 

polygons, closed, 250 
polymorphism, 339, 340 
pop-up menus (context menus), 
78-79, 107-113, 364-372 
pound sign (#), 242 
PowerPC chip, 417 
preemptive multitasking, 4, 421 
PRELOAD, 101 
printers, 390-392 
printf, 346 

procedures, window, 18, 43 
processes, 300-302 
Program Manager, 8 
PROGTYPE, 328 
Prolog, 409 


Prominare, 149, 411 
PROTMODE, 290 
PS (presentation space), 49-51, 
53-57 

Cached Micro-Presentation 
Space, 256-258 
fonts and, 61-62 
Micro-Presentation Space, 
256-258 

Normal Presentation Space, 
256-258 

three, basic description of, 
255-264 

WinDrawBitmap and, 131 
pszFileName, 361 
pszName, 377 
pszOKButton, 146 
PSZs, 54, 204,214, 234 
pszText, 234 
pszTitle, 146 
PTHINGDATA, 288 
PTOPPINGDLGDATA, 382 
PTRLIB.RC, 293-294 
PU_ARBITRAR, 258 
PU.HCONSTRAIN, 112 
PUJHIGHENGLISH, 257 
PUJKEYBOARD, 113 
PUJLOENGLISH, 257 
PU.MOUSEBUTTON1DOWN, 
113-114 

PU_MOUSEBUTTON2DOWN, 

113-114 

PLLMOUSEBUTTON3DOWN, 
113-114 
PUJPELS, 258 

PLLPOSITIONONITEM, 112, 113 
PILSELECTITEM, 113 
PU.TWIPS, 257 
PUJ/CONSTRAIN, 112 
PVOID, 288 

PWNDPARAMS, 177-178 
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query functions, basic 
description of, 52 
quitting applications, 140-142 
quotes (“), 103, 120 
QW_PARENT, 86 
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RAM (random-access 
memory), xxix 
raster fonts (bitmap fonts), 
254-255, 268, 272 
raster operations, 254-255 
RC.EXE (Developer’s Toolkit), 
101,294 

RCLINCLUDE, 173 
rcl.yBottom, 60 
rcl.yTop, 60 
re-entrant code, 68 
rectangles, 51-52, 58-60 
RECTL, 51-52 

registration, basic description 
of, 42-43. See also 
WinRegisterClass 
releaseorder directives, 348-350 
REMOVEFONTS, 328 
resid, 377 

resource editors, 149-152 
definition of, 172 
Resource Workshop, 149, 
151-152, 154, 172 
tab order and, 180 
resource files, 100-103, 105, 

107, 114. See also specific 

files 

context menus and, 366 
controls and, 170-171, 173 
dialogs and, 144-145, 149-153 
DLLs and, 293-297 
icons and, 124 
menus and, 100-103, 105, 
107, 114, 118-119 
semaphores and, 313-319 
threads and, 309-310 
restoring object data, 384-386 
REXX, 384, 413 

basic description of, 408 
use of backslashs in, 325 
WPS and, 321-322, 325, 
326-329 

REXX.CMD, 358-359 
RGB (red-green-blue) color, 
232, 248 

Ritchie, Dennis, 23 
ROP.DSTINVERT, 255 
ROP.MERGECOPY, 255 



ROP_MERGEPAINT, 255 
ROP_NOTSRCERASE, 255 
ROP_NOTSRCOPY, 255 
ROP_ONE, 255 
ROP_PATCOPY, 255 
ROP_PATINVERT, 255 
ROP_PATPAINT, 255 
ROP_SCRINVERT, 255 
ROP_SRCAND, 255 
ROP_SRCCOPY, 255 
ROP_SRCERASE, 255 
ROP_SRCINVERT, 255, 259 
ROP_SRCPAINT, 255 
ROP_ZERO, 255 

rotation, font/text, 275-276, 277 

• s • 

saving 

object data, in the settings 
notebook, 384-386 
objects, 330 
SBJENDSCROLL, 90 
SB_LINEDOWN, 90 
SB_LINELEFT, 90 
SB_LINERIGHT, 90 
SB_LINEUP, 90 
SB_PAGEDOWN, 90 
SBJPAGELEFT, 90 
SBJPAGERIGHT, 90 
SB_PAGEUP, 90 
SB_SLIDERPOSITION, 90 
SB_SLIDERTRACK, 90-91 
SBM.SETSCROLLBAR, 87 
SBM.THUMBSIZE, 89 
SBMP_SBUPARROW, 236 
SBMP.UP ARROW, 132 
SC.EXE, 343-344, 348-349, 351, 
353, 362-363, 376, 383 
scale, slider, 220 
SCALE 1, 222 
SCALE2, 222 
scan code, 120, 422 
screen resolution, 19 
scroll bars, 85-92, 161 
SDI (Single Document 
Interface), 11 
selection, extended/ 
multiple, 200 


semaphores, 299, 311-320 
sensors, short-range (SRS), 

231, 238 

SEPARATOR keyword, 103 
sessions, 300-302 
SET, 328 

_set_chorus(), 343, 347, 348 
_set_field(), 342 
SetNameO, 339, 340 
settings notebook, 134-135, 
375-386, 389 

adding Window pages to, 
377-378 

building, steps for, 378-381 
initializing object data in, 
383-384 

removing Window pages 
from, 376-377 
requesting, actions that 
occur during, 376 
saving/restoring object data 
in,384-386 

SETTINGS_PAGE_NUMBERS, 

378 

SETTINGS_PAGE_REMOVED, 

376 

setup strings, 325, 326-329 
Shakespeare, William, 312-313 
Shift+FlO, 79, 109 
SHORT1, 203-206, 216, 224, 238 
SHORT1FROMMP, 76, 87, 238 
SHORT2, 89-90, 205, 217, 224 
SHORT2FROMMP, 76, 87 
SHORT integers, 258, 274 
SID_PROGIND, 177 
SL_SLIDER, 219 
slash character, 325, 342 
slider(s), 219-230 
basics, 220-223 
callbacks, 226-229 
messages, 223-226 
SLIDER.C, 219, 229 
SLIDER.DLG, 229 
SLIDER.H, 229 

SLIDER_INVALID_PARAMETERS, 
223 

SLIDER.RC, 229 
SLM_ADDDETENT, 224-225 


SLM_QUERYDETENTPOS, 

224-225 

SLM_QUERYSCALETEXT, 

224-225 

SLM_QUERYSLIDERINFO, 

224-225 

SLM.QUERYTICKPOS, 224-225 
SLM_QUERYTICKSIZE, 224-225 
SLM.REMOVEDETENT, 

224-225 

SLM_SETSCALETEXT, 224-225 
SLM_SETSLIDERINFO, 223, 
224-225 

SLM_SETTICKSIZE, 224-225 
SLN_CHANGE, 226 
SLN_SLIDERTRACK, 226 
SLS_BOTTOM, 221 
SLS_BUTTONSLEFT, 222 
SLSJBUTTONSRIGHT, 222 
SLSJBUTTONSTOP, 222 
SLS_CENTER, 221 
SLS_HOMEBOTTON, 222 
SLS_HOMELEFT, 222 
SLS_HOMERIGHT, 222 
SLS_HOMETOP, 222 
SLS_HORIZONTAL, 221 
SLS_LEFT, 221 
SLS_PRIMARYSCALE 1, 221 
SLS_PRIMARYSCALE2, 221 
SLSJRIGHT, 221 
SLS_SNAPTOINCREMENT, 
222-223 
SLS_TOP, 221 
SLS_VERTICAL, 221 
SM.QUERYHANDLE, 177 
SM.SETHANDLE, 177 
SMAJNCREMENTVALUE, 225 
SMA.SHAFTDIMENSIONS, 
224-225 

SMA_SHAFTPOSITION, 224-225 
SMA_SLIDERARMDIMENSIONS, 
224-225 

SMA_SLIDERARMPOSITION, 

224-225 

Smalltalk, 337, 338, 408 
SNL_CHANGE, 226 
SNL_KILLFOCUS, 226 
SNL_SETFOCUS, 226 
SNL_SLIDERTRACK, 226 
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SOM (System Object Model), 9, 
335-354 

basic description of, 337-338 
classes, basic format of, 
341-342 

classes, updating, 350-352 
clients, 346-350 
Direct-To-Som capability 
and, 338 

IDL (Interface Definition 
Language), 338, 340-345, 
348-351, 362, 366-368, 
379, 387-388 
libraries, 352-354 
the pizza-making program 
and, 355, 358, 359, 360, 
363, 368, 383 

programs, five steps required 
to build, 340-343 
releaseorder directives and, 
348-350 

SOM1.C, 340-341, 345-347, 350 
SOM 1.IDL, 343-344, 351-353 
SOM1.IH, 344-345 
SOM1.LIB, 353 
SOMClass, 360 
SOMClassMgrObject, 363 
somDefaultlnit, 350, 351 
SOMFree, 363, 364 
_somGetClassName, 397 
SOMJdFromString, 363 
_somLocateClassFile, 363 
SOMObject, 341,350, 389 
somSelf, 345, 385 
SP_COL, 231 

SPJDAY, 211, 214, 216, 217-218 
SP_MONTH, 211,216, 218 
SPJROW, 231 
SP_SPIN, 219 
SP_YEAR, 211,214, 216 
SPBM_OVERRIDESETLIMITS, 
213, 214 

SPBM_QUERYLIMITS, 213 
SPBM_QUERYVALUE, 213, 214, 
215-216, 218 

SPBM_SETARRAY, 213, 214-216 
SPBM_SETCURRENTVALUE, 213 
SPBM_SETLIMITS, 213, 214, 218 
SPBM_SETMASTER, 213 


SPBM_SETTEXTLIMIT, 213 
SPBMJSPINDOWN, 213 
SPBM_SPINUP, 213 
SPBN_CHANGE, 217, 218 
SPBN_DOWNARROW, 217 
SPBN_ENDSPIN, 217 
SPBN_KILLFOCUS, 217 
SPBN.SETFOCUS, 217 
SPBN_UPARROW, 217 
SPBQ_ALWAYSUPDATE, 214, 
216,218 

SPBQ_DONOTUPDATE, 214 
SPBQ_UPDATEIFVALID, 214, 
216,218 

SPBS.ALLCHARACTERS, 212 
SPBS_FASTSPIN, 212 
SPBS_JUSTCENTER, 212 
SPBS.JUSTLEFT, 212 
SPBS.JUSTRIGHT, 212 
SPBS_MASTER, 212 
SPBS.NUMERICONLY, 212 
SPBS.PADWITHZEROS, 212 
SPBSJREADONLY, 212 
SPBS.SERVANT, 212 
speech recognition systems, 
416-417 

SpeedSoft, 409, 412 
spin button(s), 211-218 
callbacks, 216-218 
messages, 213-216 
styles, 212 
spOpen, 401 
SPTR_APPICON, 129 
SPTR_ARROW, 129 
SPTR_FILE, 129 
SPTR_FOLDER, 129 
SPTRJCONERROR, 129 
SPTRJCONINFORMATION, 129 
SPTRJCONQUESTION, 129 
SPTRJCONWARNING, 129 
SPTRJLLEGAL, 129 
SPTR_MOVE, 129 
SPTR_MULTFILE, 129 
SPTR_PROGRAM, 129 
SPTR_SIZE, 129 
SPTRJSIZENESW, 129 
SPTR_SIZENS, 129 
SPTR_SIZENWSE, 129 
SPTR_SIZEWE, 129 


SPTR_TEXT, 129 
SPTR_WAIT, 129 
SRS (Short-Range Sensors), 
231,238 

SS_AUTOSIZE, 175-176 
SS_BGNDFRAME, 175 
SS_BGNDRECT, 175 
SS_BITMAP, 175 
SS_FGNDFRAME, 175 
SS_FGNDRECT, 175 
SS_GROUPBOX, 175 
SS_HALFTONEFRAME, 175 
SS_HALFTONERECT, 175 
SSJCON, 175 
SS_SYSICON, 175 
SS.TEXT, 175 

STACK_COMMITTED, 303-304 
STACK_SPARSE, 303-304 
standard windows, 30, 33-42. 
See also WinCreateStd- 
Window 

STARTUPDIR, 328 
Startup folder, 323 
static windows, 167 
string(s) 

data type, 342 
handles to, 394 
searching for, in list boxes, 
205-206 

setup strings, 325, 326-329 
STRING.H, 48 
strlen, 48 
strong typing, 23 
styles 
class, 43 

menu item, 103, 104-105 
window, 34-37 
SUBDLL, 293 
SUBDLL.C, 287-289 
SUBDLL.DLL, 292 
SUBDLL.H, 286-289 
SWCNTRL, 171 
symbols. See also characters 
* (asterisk), xxxv, 342 
\ (backslash), 325 
, (comma), 103, 104-105 
“ (double quotes), 103, 120 
... (ellipses), 379 
- (em dash), 93 



/ (forward slash), 342 
# (pound sign), 242 
~ (tilde character), 55 
SysCopyObject, 330-331 
SysCreateObject, 324, 325, 

326, 360 

SysCreateShadow, 330-331 
SysDestroyObject, 330 
SysMoveObject, 330-331 
SysSaveObject, 330 
SysSetlcon, 326 
SysSetObjectData, 329-330 
system 

events, 84-85 
pointers, 129-130 
System folder, 323 
System Object Model. See SOM 
(System Object Model) 
System Setup folder, 19, 75, 

80, 323 

szFaceName, 271, 282 
szFamilyName, 282 
szFullFile, 146 

• T • 

tables 

accelerator, 103, 119-121, 125 
color, 248 
tab order, 179-180 
Taligent, 415 
TARGET.PTR, 297 
Task List, 109, 140, 171 
TEMPLATE, 327 
templates, 8-9, 18, 327, 323 
Templates folder, 8, 323 
TERMGLOBAL, 290 
TERMINSTANCE, 290 
TESTICO.ICO, 124, 293 
text edits, requesting, 78-79 
text+written, 58 
thingCreateThing, 288-289, 293 
THREAD.C, 305-311 
THREAD.H, 313 
THREAD.RC, 313 
threads, 93, 299-320 
creating/destroying, 

302-304 

definition of, 422 
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tick, 220-221 
tick mark, 221 
tilde character (~), 55 
TITLE, 327 
titlebar 

ownership and, 21-22 

position of, in the Enhanced 
Editor, 17 

top-level windows, 19 
Topping class, 358-403 
TOPPING.DLL, 357 
TOPPING.IDL, 357 
transient objects, 357 
TREEFONT, 328 
TREEVIEW, 328 
TXTBOXJBOTTOMLEFT, 269 
TXTBOX_BOTTOMRIGHT, 269 
TXTBOX_COUNT, 269-270 
TXTBOXJTOPLEFT, 269 
TXTBOX.TOPRIGHT, 269 
type checking, 23-24 

• u • 

ulBufLen, 234 
ulFqFCount, 146 
ulltemCount, 204 
ulItemID, 394 

ULONG, 23, 49, 181,234,310, 
368, 378-379 
ULONG ResourcelD, 42 
ulPagelnsertld, 377, 378 
underscore characters, 347-348 
updating, SOM classes, 350-352 
usCodePage, 282 
USEDLL, 293 
USEDLL.C, 292 
USEDLL.EXE, 292 
USEITEM, 402 

USESOM1.C, 347, 350, 352, 353 
USESOMl.EXE, 347, 353 
USHORT, 181,223, 234 
usOperation, 392 
usPagelnsertFlags, 377 
usPageStyleFlags, 377 
usRecordLength, 271 
usReserved, 392 
usSettingsFlags, 377 


• u • 

ValidateDragAndDrop, 391, 

392, 397 

validation, data, 197, 419 
VALSET.H, 242 
value set(s), 231-242 
callbacks, 237-239 
messages, 234-236 
sample program, 239-242 
styles, 232-234 

vector images, 268, 272-281, 422 
VIA_BITMAP, 234 
VIA_COLORINDEX, 234 
VIA_DISABLED, 234 
VIA_DRAGGABLE, 234, 238 
VIA_DROPONABLE, 234, 238 
VIAJCON, 234 
VIA_OWNERDRAW, 234 
VIAJRGB, 234 
VIA_TEXT, 234 
views 

Details view, 328, 331, 357 
setting up new, 397-403 
virtual consoles, 301 
VIRTUALKEY, 120 
virtual key code, 82, 120 
Visual Basic, 336 
VK_ALT, 84 
VK_ALTGRAF, 84 
VKJBACKSPACE, 84 
VK_BACKTAB, 84 
VK_BREAK, 84 
VK_CAPSLOCK, 84 
VK_CTRL, 84 
VK_DELETE, 84 
VKJDOWN, 84 
VK_END, 84 
VK_ENTER, 84 
VK_ESC, 84 
VK_F1, 84 
VK_F2, 84 
VK_F3, 84 
VK_F4, 84 
VK_F5, 84 
VK_F6, 84 
VK_F7, 84 
VK_F8, 84 
VK_F9, 84 
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VK_F10, 84 
VK_F11, 84 
VK_F12, 84 
VK_HOME, 84 
VKJNSERT, 84 
VKJLEFT, 84 
VKJNEWLINE, 84 
VK_NUMLOCK, 84 
VK_P AGED OWN, 84 
VK_PAGEUP, 84 
VK_PAUSE, 84 
VK_PRINTSCRN, 84 
VK.RIGHT, 84 
VKJSCRLLOCK, 84 
VK_SHIFT, 84 
VK_SPACE, 84 
VK_SYSRQ, 84 
VK_TAB, 84 
VKJJP, 82 

VM_QUERYITEM, 235 
VM_QUERYITEMATTR, 235 
VM.QUERYMETRICS, 235 
VM_QUERYSELECTEDITEM, 235 
VM_SELECTITEM, 235 
VM_SETITEM, 235, 236 
VM_SETITEMATTR, 235, 236 
VM_SETMETTRICS, 235 
VMAJTEMSIZE, 235 
VMAJTEMSPACING, 235 
VNJ9RAGLEAVE, 238 
VN_DRAGOVER, 238 
VN_DROP, 238 
VN_DROPHELP, 238 
VN_ENTER, 237 
VN_HELP, 237 
VN_KILLFOCUS, 237 
VN_SELECT, 237 
VN_SETFOCUS, 237 
voice recognition systems, 
416-417 

VS_BITMAP, 232 
VSJBORDER, 233 
VS_COLORINDEX, 232 
VSJCON, 232 
VSJTEMBORDER, 233 
VS_OWNERDRAW, 234 
VS_RGB, 232 
VSJRIGHTTOLEFT, 234 
VS_TEXT (style), 232 
VSTEXT (data type), 234 


• w * 

warning messages, 348-349 
Watcom, 10, 25, 100, 72, 150, 
347, 412 

WAVE.BMP, 118 
WC_BUTTON, 171, 183-185 
WC_COMBO, 199 
WC.COMBOBOX, 171 
WC.CONTAINER, 171, 355, 387 
WC_DIALOG, 168 
WCJENTRYFIELD, 171, 193 
WC.FRAME, 171, 246 
WC_LISTBOX, 171, 199, 206 
WCJMENU, 171 
WCJV1LE, 171 
WC.NOTEBOOK, 171, 355 
WC_SCROLLBAR, 171 
WC_SLIDER, 171,221,225 
WC.SPINBUTTON, 171 
WC_STATIC, 171, 172-174, 177, 
179, 181 

WCJTITLEBAR, 171 
WC.VALUESET, 171 
WEBB.BMP, 118 
While loop, 60, 140 
WinBeginPaint, 50-51, 64, 256 
WinCancelShutdown, 141 
WinCreateMsgQueue, 29, 

32-33, 46, 139 
WinCreateObject, 384 
WinCreateStdWindow, 29, 30, 
31,33-42, 45, 86, 105, 125, 
138-139, 152, 194, 336 
WinCreateWindow, 29, 29, 46, 
171-172, 174, 176 
WinDefDlgProc, 155, 186 
WinDefWindowProc, 30, 45, 85, 
141, 153, 170 

WinDestroyMsgQueue, 30, 46 
WinDestroyPointer, 127-128 
WinDestroyWindow, 30, 46, 108 
WinDispatchMsg, 30, 32, 33, 
44-45, 140 

WinDlgBox, 153, 155, 158 
window(s) 

basic description of, 16-18 
child, 19-22, 86, 110 
client, 31,37, 53, 110 
frame, 18, 30, 38-41 


parent, 19-22, 34, 37, 86, 110 
procedures, 18, 43 
standard, 30, 33-42 
words, 66-67, 422 
WINDOWAPI, 290 
WINDOWCOMPAT, 290 
WINDOWDATA, 71-72, 89, 259 
Windows (Microsoft) 
as a modal operating 
system, 8 

as a multitasking operating 
system, 4 

Windows NT (Microsoft), 3 
Windows 95 (Microsoft), 3 
WinDrawBitmap, 131-132, 251 
WinDrawText, 53-57, 58, 62, 

269, 273 

WinEnableControl, 180 
WinEnableWindow, 157 
WinEndPaint, 50-51, 64, 247, 256 
WinFileDlg, 145, 147 
WinFillRect, 52, 56, 247 
WinGetCurrentTime, 94 
WinGetMsg, 30, 32, 33, 

44-45, 140 

WinGetSysBitmap, 132 
Winlnitialize, 29, 30-32, 46 
WinlnvalidateRect, 72, 84 
WinLoadDlg, 194 
WinLoadMenu, 108 
WinLoadPointer, 127 
WinMapWindowPoints, 110 
WinMessageBox, 135-140 
WinPopupMenu, 111-113 
WinPostMessage, 305 
WinQueryButtonCheckstate, 
187-188 

WinQueryDlgltemShort, 180 
WinQueryDlgltemT ext- 
Length, 181 
WinQueryMsgPos, 44 
WinQueryMsgTime, 44 
WinQueryPointerPos, 109-111 
WinQuerySysPointer, 129-130 
WinQueryWindow, 86, 91-93 
WinQueryWindowPtr, 66-67, 
128, 336 

WinQueryWindowRect, 52, 85 
WinQueryWindowText, 161, 177 



WinRegisterClass, 29, 33, 41, 
42-43, 45, 66, 139 
WinSendDlgltemMsg, 181 
WinSendMsg, 87, 89, 91-93, 
114, 117-118, 181,305 
WinSetColor, 178 
WinSetDlgltemText, 181 
WinSetFocus, 401 
WinSetPointer, 127 
WinSetWindowParams, 195 
WinSetWindowPtr, 336 
WinSetWindowText, 176-177 
WinShowWindow, 401 
WinStartTimer, 93-95 
WinStopTimer, 93-95 
WinTerminate, 30, 46 
WinWindowFromID, 91-93, 

101, 108, 157, 181 
WINWORKPLACE, 358 
Wirth, Niklaus, 23-24 
WM_ACTIVATE, 74 
WM JBUTTON 1 CLICK, 80 
WM_BUTTONlDOWN, 74-76 
WM_BUTTONxDOWN, 75, 112 
WM.CHANGEFOCUS, 382 
WM_CHAR, 81-83 
WM_CLOSE, 85, 141, 170 
WM_COMMAND, 78, 113, 120, 
155, 161, 178, 186, 187 
WM_CONTEXT, 110 
WM_CONTEXTMENU, 109, 364 
WM_CONTROL, 178, 188, 

195, 206, 208,216-217, 
237, 238 

WM_CONTROLPOINTER, 

226, 237 

WM_CREATE, 68-71, 73, 294 
WM.DESTROY, 68-71, 73, 294, 
402-403 

WM_DRAWITEM, 206, 226, 237 
WM_HELP, 113, 120, 185, 237 
WMJNITDLG, 153, 158 
WMJVIATCHMNEMONIC, 177 
WM_MEASURE, 206 
WM.MOUSEMOVE, 128 
WMJPAINT, 49, 51, 64, 65, 72, 
73, 75, 246, 247, 311 
WMJPROGRESS, 177 


Index 
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WM_QUERYWINDOWP ARAMS, 
177-178 

WM_QUIT, 141-142, 170, 403 
WM.SAVEAPPLICATION, 142 
WM_SETWINDOWP ARAMS, 
177-178 
WM_SHOW, 85 
WM_SIZE, 85 
WM.SYSCOMMAND, 113, 

120, 185 
WM_TIMER, 94 
WM_VSCROLL, 89 
word processing, 12-13, 33, 135 
words, window, 66-67, 422 
WORKAREA, 328 
WorkFrame/2 (IBM), 10-13, 101 
WPAbstract, 357, 361, 375-376, 
389, 390 

wpAddLockuplPage, 376 
wpAddLockup2Page, 376 
wpAddLockup3Page, 376 
wpAddObjectGeneralPage, 376 
wpAdd<PageName><Page- 
Number>Page, 376 
wpAddSettingsPage, 376, 378 
WPBitmap, 324 
wpclsNew, 384 
wpclsQuerylconData, 361, 

362, 364 

wpclsQueryStyle, 389 
wpclsQueryTitle, 389 
WPColorPalette, 324 
WPCommandFile, 324 
wpCopyObject, 370 
WPDataFile, 324, 389 
wpDelete, 370 
WPDesktop, 324 
wpDragOver, 391, 396 
WPDrives, 324 
WPFileSystem, 357 
wpFilterPopupMenu, 

364-365, 368 
WPFolder, 324-325, 328, 

329, 390 

WPFontPalette, 324 
WPIcon, 324 
wpInitData, 383-384 
wpInsertPopupMenuItems, 364 
wpInsertSettingsPage, 376 


WPLaunchPad, 324 
WPMENUID_OPEN, 366 
WPMinWinViewer, 324 
wpModifyPopupMenu, 364-366 
WP Object, 325-326, 329 
wpOpen, 397, 399-400 
wpOpenView, 402 
WPPalette, 324 
WPPointer, 324 
WPPrinter, 324 
WPProgramFile, 324, 329 
WPPrograms, 325, 328 
wpRestoreLong, 385 
wpRestoreState, 383-385 
wpRestoreString, 385 
WPS (Workplace Shell), 8-9 
the Black Hole and, 391 
classes, summary of, 324 
class styles, 389-390 
context menus and, 107 
controls and, 167 
dialogs and, 149 
DLLs and, 297 
fonts and, 62 
“Hello, World” program 
and, 53 

modeless dialogs and, 
163-164, 149 

mouse messages and, 78, 

79, 80 

object IDs and, 322-323, 325 
overview of, 355-373 
vs. the PM, 10-13 
pointers and, 126 
polymorphism and, 340 
saving/destroying objects 
and, 330 

setting object data and, 
329-330 

templates and, 18 
threads and, 301, 304 
tricks, 321-332 
user functions, 330-331 
Wp* API and, 245 
wpSaveLong, 385 
wpSaveState, 385 
wpSaveString, 385 
WPSchemePalette, 324 
wpSetupOnce, 383-384 
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WPShadow, 324 
WPShredder, 324 
wpslnit, 383-384 
WPSound, 324 

wpTopFilterPopupMenu, 366, 
368-369 

WPTransient, 357 
_wpViewObject, 399-400 
WS_ANIMATE, 34, 37, 174 
WS_CLIPCHILDREN, 34, 37 
WS_CLIPSIBLINGS, 34, 37, 174 
WS_DIASBLED, 34, 37, 174 
WS_GROUP, 34, 37, 174, 187 


WS_MAXIMIZED, 34, 37 
WS_MINIMIZED, 34, 37 
WS_PARENTCLIP, 34, 37, 174 
WS_SAVEBITS, 34 
WS_SYNCPAINT, 34, 174 
WS_TABSTOP, 34, 37, 174 
WS_VISIBLE, 34-35, 174 

• x • 

xDrop, 392-393 
x field, 146 


® y m 

yDrop, 392-393 
y field, 146 

• Z • 

ZIGZAG.BMP, 118 
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Let These Icons Guide You! 

Points out Warp-specific 
information for Warp 3.X 

flags a danger you should 
watch out for in the 
design of your program 

Alerts you to nerdy 
technical discussions you 
can skip if you want to 
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READER LEVEL 
Beginning to 
intermediate 

COMPUTER 
BOOK SHELVING 
CATEGORY 

PCs/ 

Programming/ 

OS/2 

$19.99 USA 
$26.99 Canada 
£18.99 UK 
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